feat: propagate trace context through outbox and add pipeline saturation metrics

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 19:54:37 +03:00
co-authored by Claude Opus 5.5
parent ff0073e8e3
commit 72cfa9aaf6
64 changed files with 4699 additions and 552 deletions
+15
View File
@@ -29,6 +29,7 @@ from src.core.services import (
SessionService,
UserService,
)
from src.infra import telemetry
from src.infra.cache.instance import cache
from src.infra.db import ping
from src.infra.db.scope import deadline_scope
@@ -124,6 +125,20 @@ AttachmentServiceDep = Annotated[
]
async def get_trace_context() -> dataclasses.TraceContextDTO | None:
"""Контекст W3C текущего span — server span запроса — для задания
загрузки (design change `job-trace-propagation`, решение 4); без
телеметрии — `None`. Сервис телеметрию не импортирует: контекст приходит
значением, как `owner_id`."""
return telemetry.current_trace_context()
TraceContextDep = Annotated[
dataclasses.TraceContextDTO | None,
Depends(get_trace_context),
]
# схемы basicAuth и bearerAuth из contracts/openapi.json: объявлены в
# /openapi.json и дают кнопку Authorize в /docs. auto_error=False — нет
# заголовка или схема чужая даёт None, а 401 в формате контракта бросает
+11 -3
View File
@@ -15,7 +15,11 @@ from fastapi.responses import StreamingResponse
from starlette.background import BackgroundTask
from starlette.requests import ClientDisconnect
from src.api.dependencies import AttachmentServiceDep, CurrentUser
from src.api.dependencies import (
AttachmentServiceDep,
CurrentUser,
TraceContextDep,
)
from src.api.schemas import Attachment, DisplayFilename, UuidIn
from src.core import exceptions
from src.schemas.enums import AttachmentVariantName, ImageType
@@ -112,9 +116,12 @@ async def upload_attachment(
filename: FilenameQuery,
request: Request,
attachments: AttachmentServiceDep,
trace_context: TraceContextDep,
) -> Attachment:
"""202 — оригинал в staging, метаданные и задание в PostgreSQL, брокер
подтвердил сообщение; итог клиент узнаёт по метаданным.
"""202 — оригинал в staging, вложение `queued` и задание в PostgreSQL
одной транзакцией; сообщение публикует relay, итог клиент узнаёт по
метаданным. Контекст server span загрузки сохраняется в задании (design
change `job-trace-propagation`, решение 4).
Тело не читается, пока не пройдены вход, параметры, членство,
`Content-Type` и `Content-Length` (спек «Порядок проверок загрузки»).
@@ -129,6 +136,7 @@ async def upload_attachment(
media_type=_media_type(request),
content_length=_content_length(request),
body=_body(request),
trace_context=trace_context,
)
return Attachment.model_validate(attachment)
+6 -4
View File
@@ -457,12 +457,14 @@ class Relay(BaseModel):
class Telemetry(BaseModel):
"""Телеметрия API и worker (design change `otel-telemetry`, решение 8).
"""Телеметрия API, worker и relay (design change `otel-telemetry`, решение
8; relay — `job-trace-propagation`, решение 7).
Включает её стенд compose окружением `TELEMETRY__ENABLED` и
`TELEMETRY__OTLP_ENDPOINT` у реплик API и worker; интервалы и очереди — из
`config.toml`. Переменные `OTEL_*` настройками не являются: SDK собирается
только из этих полей. Relay, уборщик и миграции секцию не читают.
`TELEMETRY__OTLP_ENDPOINT` у реплик API, worker и relay; интервалы и
очереди — из `config.toml`. Переменные `OTEL_*` настройками не являются: SDK
собирается только из этих полей. Уборщик, миграции и команда replay секцию
не применяют.
"""
# выключена — ни провайдеров SDK, ни отправки, ни полей трассы в журнале
+17 -1
View File
@@ -18,7 +18,9 @@ class AbstractAttachmentJobRepository(abc.ABC):
*,
job: dataclasses.AttachmentJobDTO,
) -> dataclasses.AttachmentJobDTO:
"""Новая работа; вложение становится `queued` в той же транзакции."""
"""Новая работа; вложение становится `queued` в той же транзакции.
`traceparent` и `tracestate` задания сохраняются как есть и читаются
всеми выборками заданий."""
@abc.abstractmethod
async def lock_job(
@@ -108,6 +110,20 @@ class AbstractAttachmentJobRepository(abc.ABC):
незавершённых не меньше `limit`. Цена не растёт с превышением, само
число выше `limit` неточно."""
@abc.abstractmethod
async def queue_snapshot(
self,
*,
now: datetime,
) -> dataclasses.QueueSnapshotDTO:
"""Незавершённые задания по стадиям на `now`: `scheduled` — `queued`
без отметки публикации со сроком (`next_attempt_at`, иначе
`created_at`) позже `now`, `outbox` — то же со сроком не позже `now`,
`published` — `queued` с отметкой, `processing` — идёт попытка. Сумма
стадий — все `queued` и `processing`. `oldest_created_at` —
наименьший `created_at` среди них, `None` — незавершённых нет;
`taken_at` = `now`."""
@abc.abstractmethod
async def mark_published(
self,
+62
View File
@@ -55,6 +55,8 @@ _JOB_COLUMNS = (
AttachmentJob.lease_expires_at,
AttachmentJob.published_at,
AttachmentJob.finished_at,
AttachmentJob.traceparent,
AttachmentJob.tracestate,
)
# срок задания: то же выражение, что в индексе ix_attachment_jobs_outbox
@@ -108,6 +110,8 @@ class SqlAlchemyAttachmentJobRepository(AbstractAttachmentJobRepository):
attempt=job.attempt,
created_at=job.created_at,
updated_at=job.updated_at,
traceparent=job.traceparent,
tracestate=job.tracestate,
),
)
return job
@@ -295,6 +299,64 @@ class SqlAlchemyAttachmentJobRepository(AbstractAttachmentJobRepository):
statement = select(counts[0] + counts[1] + counts[2])
return (await self._session.execute(statement)).scalar_one()
async def queue_snapshot(
self,
*,
now: datetime,
) -> dataclasses.QueueSnapshotDTO:
"""Стадии незавершённых заданий и приём старейшего — одним выражением
(design change `job-trace-propagation`, решение 9). Каждый подзапрос
совпадает с условием своего частичного индекса (outbox по выражению
срока, опубликованные, аренда); состояние — константой, иначе общий
план — Seq Scan. Незавершённых ограниченно (предел приёма)."""
published = (_queued(), AttachmentJob.published_at.is_not(None))
processing = (
AttachmentJob.state
== literal(
AttachmentJobState.PROCESSING.value,
literal_execute=True,
),
)
def count(*condition: ColumnElement[bool]) -> ColumnElement[int]:
return (
select(func.count())
.select_from(AttachmentJob)
.where(*condition)
.scalar_subquery()
)
def oldest(
*condition: ColumnElement[bool],
) -> ColumnElement[datetime]:
return (
select(func.min(AttachmentJob.created_at))
.where(*condition)
.scalar_subquery()
)
statement = select(
count(*_outbox_condition(), now < _DUE_AT).label("scheduled"),
count(*_outbox_condition(), now >= _DUE_AT).label("outbox"),
count(*published).label("published"),
count(*processing).label("processing"),
# LEAST пропускает NULL: пустая группа возраст не задаёт
func.least(
oldest(*_outbox_condition()),
oldest(*published),
oldest(*processing),
).label("oldest_created_at"),
)
row = (await self._session.execute(statement)).one()
return dataclasses.QueueSnapshotDTO(
taken_at=now,
scheduled=row.scheduled,
outbox=row.outbox,
published=row.published,
processing=row.processing,
oldest_created_at=row.oldest_created_at,
)
async def mark_published(
self,
*,
+18
View File
@@ -90,10 +90,14 @@ class AttachmentService:
media_type: str | None,
content_length: int | None,
body: AsyncIterator[bytes],
trace_context: dataclasses.TraceContextDTO | None = None,
) -> dataclasses.AttachmentFullDTO:
"""Приём оригинала; 202 — оригинал в staging, вложение `queued` и его
задание зафиксированы. Брокера в пути запроса нет: намерение до него
доводит relay (design change `pipeline-reliability`, решение 1).
`trace_context` — контекст W3C запроса загрузки от слоя API: он
пишется в задание вместе с намерением (design change
`job-trace-propagation`, решение 4), `None` — без контекста.
Порядок проверок — спек «Порядок проверок загрузки»: одним блоком и
без места членство (404), `Content-Type` (415), `Content-Length` (413)
@@ -160,6 +164,7 @@ class AttachmentService:
body=body,
started=started,
waited_ms=waited_ms,
trace_context=trace_context,
log=log,
)
except exceptions.UploadsBusy:
@@ -181,6 +186,7 @@ class AttachmentService:
body: AsyncIterator[bytes],
started: float,
waited_ms: int,
trace_context: dataclasses.TraceContextDTO | None,
log: AbstractLogger,
) -> dataclasses.AttachmentFullDTO:
"""Путь загрузки на занятом месте: тело, проверка, запись."""
@@ -256,6 +262,7 @@ class AttachmentService:
queued, job = await self._mark_queued(
attachment_id=attachment_id,
staging=staging,
trace_context=trace_context,
log=log,
)
log.info(
@@ -275,6 +282,7 @@ class AttachmentService:
*,
attachment_id: UUID,
staging: str,
trace_context: dataclasses.TraceContextDTO | None,
log: AbstractLogger,
) -> tuple[dataclasses.AttachmentFullDTO, dataclasses.AttachmentJobDTO]:
"""`pending` → `queued` и задание одной транзакцией: устойчивое
@@ -307,6 +315,16 @@ class AttachmentService:
attempt=0,
created_at=now,
updated_at=now,
traceparent=(
None
if trace_context is None
else trace_context.traceparent
),
tracestate=(
None
if trace_context is None
else trace_context.tracestate
),
),
)
commit_sent = True
+79 -27
View File
@@ -4,8 +4,10 @@ Design change `async-attachments`, решения 2 и 7; `pipeline-reliability`
3, 4, 6, 7. `handle` разбирает сообщение, берёт задание по таблице claim, публикует
оригинал из staging в конечный ключ, получает варианты от процесса обработки,
пишет их объекты и одной транзакцией фиксирует `ready`. Итог — исход доставки
(`JobDeliveryOutcome`, design change `otel-telemetry`, решение 11): из него
`src/worker/main.py` выводит действие с сообщением и пишет метрику.
(`JobDeliveryOutcome`, design change `otel-telemetry`, решение 11) с попыткой,
причиной, кодом ошибки и временем до готовности (`JobDeliveryResultDTO`, design
change `job-trace-propagation`, решение 8): из него `src/worker/main.py` выводит
действие с сообщением и пишет span и метрики.
Сообщение — подсказка, истина в строке задания. Worker не публикует: следующую
попытку и возврат зависшей публикует relay. Дубль при живой аренде и сообщение
@@ -21,6 +23,7 @@ import hashlib
import io
import random
import time
from dataclasses import replace
from datetime import timedelta
from pydantic import ValidationError
@@ -64,6 +67,20 @@ def retry_delay(*, attempt: int, base: float, maximum: float) -> float:
return random.uniform(delay / 2, delay) # noqa: S311
def _skipped() -> dataclasses.JobDeliveryResultDTO:
"""Сообщение без работы; номер попытки подставляет `handle` из
сообщения."""
return dataclasses.JobDeliveryResultDTO(outcome=JobDeliveryOutcome.SKIPPED)
def _reason(code: str | None) -> AttachmentJobReason | None:
"""Причина из `last_error_code`; незнакомое значение — без причины."""
try:
return None if code is None else AttachmentJobReason(code)
except ValueError:
return None
class _PermanentError(Exception):
"""Повтор не исправит: сразу `failed`."""
@@ -101,15 +118,18 @@ class AttachmentProcessingService:
*,
body: bytes,
redelivered: bool,
) -> JobDeliveryOutcome:
"""Одна доставка и её исход; отказ PostgreSQL — пауза и возврат в
очередь."""
) -> dataclasses.JobDeliveryResultDTO:
"""Одна доставка и её итог (design change `job-trace-propagation`,
решение 8): исход, попытка, причина и код ошибки, время до готовности;
отказ PostgreSQL — пауза и возврат в очередь."""
try:
message = AttachmentJobMessage.model_validate_json(body)
except ValidationError:
# содержимое сообщения и текст ошибки с его значениями — не в журнал
logger.error("Dropped malformed job message", size_bytes=len(body))
return JobDeliveryOutcome.DROPPED
return dataclasses.JobDeliveryResultDTO(
outcome=JobDeliveryOutcome.DROPPED,
)
# задача доставки своя, контекст не уходит к другим заданиям
http_request_id.set(str(message.job_id))
log = logger.bind(
@@ -117,7 +137,7 @@ class AttachmentProcessingService:
attachment_id=message.attachment_id,
)
try:
return await self._run(
result = await self._run(
message=message,
redelivered=redelivered,
log=log,
@@ -127,7 +147,14 @@ class AttachmentProcessingService:
# Причину уже записала единица работы
log.warning("Job waits for database")
await self._pause()
return JobDeliveryOutcome.REQUEUED
return dataclasses.JobDeliveryResultDTO(
outcome=JobDeliveryOutcome.REQUEUED,
attempt=message.attempt,
)
if result.outcome == JobDeliveryOutcome.SKIPPED:
# без попытки: номер — из сообщения
return replace(result, attempt=message.attempt)
return result
async def _run(
self,
@@ -135,9 +162,9 @@ class AttachmentProcessingService:
message: AttachmentJobMessage,
redelivered: bool,
log: AbstractLogger,
) -> JobDeliveryOutcome:
) -> dataclasses.JobDeliveryResultDTO:
claim = await self._claim(message=message, log=log)
if isinstance(claim, JobDeliveryOutcome):
if isinstance(claim, dataclasses.JobDeliveryResultDTO):
return claim
job, attachment, queue_wait_ms = claim
log = log.bind(attempt=job.attempt)
@@ -214,8 +241,19 @@ class AttachmentProcessingService:
render_memory_limit_applied=rendered.memory_limit_applied,
duration_ms=round((time.monotonic() - started) * 1000),
)
return JobDeliveryOutcome.READY
return JobDeliveryOutcome.SKIPPED
# от устойчивого приёма (задание записано вместе с queued) до
# фиксации ready; после replay приём — действие оператора
time_to_ready = (
(utcnow() - job.created_at).total_seconds()
if job.attempt_base == 0
else None
)
return dataclasses.JobDeliveryResultDTO(
outcome=JobDeliveryOutcome.READY,
attempt=job.attempt,
time_to_ready_seconds=time_to_ready,
)
return _skipped()
async def _claim(
self,
@@ -228,7 +266,7 @@ class AttachmentProcessingService:
dataclasses.AttachmentFullDTO,
int | None,
]
| JobDeliveryOutcome
| dataclasses.JobDeliveryResultDTO
):
"""Взять задание под блокировкой (таблица решения 3) или вернуть итог
без попытки. Сообщение без работы подтверждается: живую попытку ведёт её
@@ -237,13 +275,13 @@ class AttachmentProcessingService:
job = await self.uow.jobs.lock_job(job_id=message.job_id)
if job is None or job.attachment_id != message.attachment_id:
log.info("Skipped job message", reason="unknown")
return JobDeliveryOutcome.SKIPPED
return _skipped()
if job.state == AttachmentJobState.SUCCEEDED:
await self._check_finished(job=job, log=log)
return JobDeliveryOutcome.SKIPPED
return _skipped()
if job.state == AttachmentJobState.FAILED:
log.info("Skipped job message", reason="finished")
return JobDeliveryOutcome.SKIPPED
return _skipped()
now = utcnow()
if (
job.state == AttachmentJobState.QUEUED
@@ -252,14 +290,14 @@ class AttachmentProcessingService:
and job.next_attempt_at > now
):
log.info("Skipped job message", reason="not_due")
return JobDeliveryOutcome.SKIPPED
return _skipped()
if (
job.state == AttachmentJobState.PROCESSING
and job.lease_expires_at is not None
and job.lease_expires_at > now
):
log.info("Skipped job message", reason="busy")
return JobDeliveryOutcome.SKIPPED
return _skipped()
if self._budget_spent(job):
# попытка потеряна при исчерпанном бюджете: сообщение пришло, а
# попытка уже посчитана
@@ -275,12 +313,17 @@ class AttachmentProcessingService:
reason=job.last_error_code,
attempt=job.attempt,
)
return JobDeliveryOutcome.FAILED
return dataclasses.JobDeliveryResultDTO(
outcome=JobDeliveryOutcome.FAILED,
attempt=job.attempt,
reason=_reason(job.last_error_code),
error_code=AttachmentErrorCode.RETRY_EXHAUSTED,
)
taken = await self._start_attempt(job=job, now=now)
await self.uow.commit()
if taken is None:
log.info("Skipped job message", reason="unknown")
return JobDeliveryOutcome.SKIPPED
return _skipped()
started, attachment = taken
queue_wait_ms = (
None
@@ -505,13 +548,13 @@ class AttachmentProcessingService:
error_code: AttachmentErrorCode,
reason: AttachmentJobReason,
log: AbstractLogger,
) -> JobDeliveryOutcome:
) -> dataclasses.JobDeliveryResultDTO:
"""`failed` своей попытки; задание уже ведёт другая — без записи."""
async with self.uow:
locked = await self.uow.jobs.lock_job(job_id=job.id)
if not self._own_attempt(locked, job=job):
log.info("Skipped job message", reason="superseded")
return JobDeliveryOutcome.SKIPPED
return _skipped()
written = await self._write_failed(
job=job,
error_code=error_code,
@@ -519,13 +562,18 @@ class AttachmentProcessingService:
)
await self.uow.commit()
if not written:
return JobDeliveryOutcome.SKIPPED
return _skipped()
log.warning(
"Attachment failed",
error_code=error_code.value,
reason=reason.value,
)
return JobDeliveryOutcome.FAILED
return dataclasses.JobDeliveryResultDTO(
outcome=JobDeliveryOutcome.FAILED,
attempt=job.attempt,
reason=reason,
error_code=error_code,
)
@staticmethod
def _own_attempt(
@@ -545,7 +593,7 @@ class AttachmentProcessingService:
job: dataclasses.AttachmentJobDTO,
reason: AttachmentJobReason,
log: AbstractLogger,
) -> JobDeliveryOutcome:
) -> dataclasses.JobDeliveryResultDTO:
"""Временная ошибка: `queued` со сроком следующей попытки и ACK; её
сообщение опубликует relay, пауза места конкуренции не занимает.
Попытки исчерпаны — `failed`."""
@@ -574,7 +622,7 @@ class AttachmentProcessingService:
)
if not own:
log.info("Skipped job message", reason="superseded")
return JobDeliveryOutcome.SKIPPED
return _skipped()
await self.uow.attachments.return_to_queued(
attachment_id=job.attachment_id,
updated_at=now,
@@ -586,7 +634,11 @@ class AttachmentProcessingService:
delay_seconds=round(delay, 3),
next_attempt_at=next_attempt_at.isoformat(),
)
return JobDeliveryOutcome.RETRY
return dataclasses.JobDeliveryResultDTO(
outcome=JobDeliveryOutcome.RETRY,
attempt=job.attempt,
reason=reason,
)
async def _pause(self) -> None:
"""Пауза перед возвратом сообщения при отказе PostgreSQL; её прерывает
+34 -4
View File
@@ -36,6 +36,32 @@ def _never() -> bool:
return False
def publication(
job: dataclasses.AttachmentJobDTO,
) -> dataclasses.JobPublicationDTO:
"""Элемент публикации из строки задания (design change
`job-trace-propagation`, решение 3): номер следующей попытки, признак
replay (`attempt_base > 0`), причина повтора — прежний `last_error_code`,
контекст загрузки из колонок задания или `None`."""
trace_context = (
None
if job.traceparent is None
else dataclasses.TraceContextDTO(
traceparent=job.traceparent,
tracestate=job.tracestate,
)
)
attempt = job.attempt + 1
return dataclasses.JobPublicationDTO(
job_id=job.id,
body=build_job_body(job, attempt=attempt),
attempt=attempt,
replayed=job.attempt_base > 0,
retry_reason=job.last_error_code,
trace_context=trace_context,
)
class AttachmentRelayService:
"""`uow` — единица работы процесса relay, `publisher` — издатель с
подтверждением. Состояние предела — только для записи на его смену."""
@@ -175,10 +201,7 @@ class AttachmentRelayService:
if not jobs:
return 0, 0, backlog, 0
confirmed = await self.publisher.publish_many(
[
(job.id, build_job_body(job, attempt=job.attempt + 1))
for job in jobs
],
[publication(job) for job in jobs],
)
if confirmed:
await self.uow.jobs.mark_published(
@@ -193,6 +216,13 @@ class AttachmentRelayService:
len(jobs),
)
async def queue_snapshot(self) -> dataclasses.QueueSnapshotDTO:
"""Незавершённые задания по стадиям и приём старейшего — один блок
(design change `job-trace-propagation`, решение 9). Отказ PostgreSQL —
`ServiceUnavailable`, причину уже записала единица работы."""
async with self.uow:
return await self.uow.jobs.queue_snapshot(now=utcnow())
def _note_backlog(
self,
*,
+77 -22
View File
@@ -22,8 +22,9 @@ Design change `async-attachments`, решение 5. Соединение отк
"""
import asyncio
import re
import time
from collections.abc import AsyncIterator, Sequence
from collections.abc import AsyncIterator, Mapping, Sequence
from dataclasses import dataclass
from typing import Any
from uuid import UUID
@@ -38,11 +39,22 @@ from aio_pika.abc import (
from src.config.settings import Broker as BrokerSettings
from src.core.exceptions import BrokerUnavailable
from src.infra import telemetry
from src.infra.logger import AbstractLogger, get_logger
from src.utils.constants import ATTACHMENT_QUEUE_SUFFIX
from src.schemas.dataclasses import JobPublicationDTO, TraceContextDTO
from src.utils.constants import (
ATTACHMENT_JOB_TYPE,
ATTACHMENT_QUEUE_SUFFIX,
TRACE_HEADER_TRACEPARENT,
TRACE_HEADER_TRACESTATE,
TRACEPARENT_PATTERN,
TRACESTATE_MAX_LENGTH,
)
logger: AbstractLogger = get_logger().bind(module="broker")
_TRACEPARENT = re.compile(TRACEPARENT_PATTERN)
# закрытие прежнего соединения в фоне: при замороженном брокере оно само
# зависло бы
_BACKGROUND_CLOSE_TIMEOUT_SECONDS = 5
@@ -100,12 +112,13 @@ class JobPublisher:
async def publish_many(
self,
items: Sequence[tuple[UUID, bytes]],
items: Sequence[JobPublicationDTO],
) -> set[UUID]:
"""Пакет `(id, тело)` с подтверждением под одним сроком. Возвращает
"""Пакет публикаций с подтверждением под одним сроком. Возвращает
подтверждённые `id`. Подмножество — ошибка уже записана, соединение
сброшено: подтверждённые до срока отмечаются, исход остальных неизвестен,
и их опубликует следующий проход (возможен дубль)."""
и их опубликует следующий проход (возможен дубль). Span producer — на
каждое сообщение (design change `job-trace-propagation`, решение 3)."""
started = time.monotonic()
channel: AbstractChannel | None = None
confirmed: set[UUID] = set()
@@ -118,9 +131,9 @@ class JobPublisher:
channel = await self._get_channel()
tasks = {
asyncio.create_task(
self._publish_one(channel, body, job_id),
): job_id
for job_id, body in items
self._publish_one(channel, item),
): item.job_id
for item in items
}
remaining = deadline - asyncio.get_running_loop().time()
done, pending = await asyncio.wait(
@@ -155,21 +168,29 @@ class JobPublisher:
async def _publish_one(
self,
channel: AbstractChannel,
body: bytes,
job_id: UUID,
item: JobPublicationDTO,
) -> None:
"""Сообщение persistent в очередь через default exchange, `mandatory`:
без маршрута брокер вернёт его, и это ошибка."""
await channel.default_exchange.publish(
aio_pika.Message(
body,
content_type="application/json",
delivery_mode=aio_pika.DeliveryMode.PERSISTENT,
message_id=str(job_id),
),
routing_key=self.queue,
mandatory=True,
)
без маршрута брокер вернёт его, и это ошибка. Единственная точка
публикации: span producer под сохранённым контекстом задания, его
контекст — заголовки `traceparent` и `tracestate` (carrier); тело
прежнее. Span заканчивается после подтверждения брокером."""
with telemetry.producer_span(
queue=self.queue,
job_type=ATTACHMENT_JOB_TYPE,
publication=item,
) as headers:
await channel.default_exchange.publish(
aio_pika.Message(
item.body,
content_type="application/json",
delivery_mode=aio_pika.DeliveryMode.PERSISTENT,
message_id=str(item.job_id),
headers=headers or None,
),
routing_key=self.queue,
mandatory=True,
)
async def ready_messages(self) -> int:
"""Готовые сообщения очереди: активное объявление, которое создаёт ещё и
@@ -272,13 +293,46 @@ class JobPublisher:
await asyncio.gather(*self._close_tasks, return_exceptions=True)
def _header_text(value: object) -> str | None:
"""Строка заголовка: pamqp отдаёт `str`, не UTF-8 — `bytes`; принимается
только ASCII."""
if isinstance(value, bytes):
try:
return value.decode("ascii")
except UnicodeDecodeError:
return None
return value if isinstance(value, str) else None
def trace_context_from_headers(
headers: Mapping[str, object] | None,
) -> TraceContextDTO | None:
"""Контекст W3C из заголовков сообщения (design change
`job-trace-propagation`, решения 1, 6): `traceparent` по шаблону версии
`00`, `tracestate` не длиннее предела, иначе `None` — новая трасса, а не
ошибка. Тело и его разбор заголовки не меняют."""
if not headers:
return None
traceparent = _header_text(headers.get(TRACE_HEADER_TRACEPARENT))
if traceparent is None or _TRACEPARENT.fullmatch(traceparent) is None:
return None
tracestate = _header_text(headers.get(TRACE_HEADER_TRACESTATE))
if tracestate is not None and not (
0 < len(tracestate) <= TRACESTATE_MAX_LENGTH
):
return None
return TraceContextDTO(traceparent=traceparent, tracestate=tracestate)
@dataclass(slots=True)
class JobDelivery:
"""Сообщение от брокера; подтверждает его `src/worker/main.py`."""
"""Сообщение от брокера; подтверждает его `src/worker/main.py`.
`trace_context` — контекст создания из заголовков или `None`."""
body: bytes
redelivered: bool
_message: AbstractIncomingMessage
trace_context: TraceContextDTO | None = None
async def ack(self) -> None:
await self._settle(self._message.ack())
@@ -366,6 +420,7 @@ class JobConsumer:
body=message.body,
redelivered=bool(message.redelivered),
_message=message,
trace_context=trace_context_from_headers(message.headers),
)
async def aclose(self) -> None:
+40
View File
@@ -8,6 +8,7 @@ import asyncio
from typing import Any
import asyncpg
from sqlalchemy import exc as sa_exc
from sqlalchemy import text
from sqlalchemy.ext.asyncio import (
AsyncEngine,
@@ -15,6 +16,7 @@ from sqlalchemy.ext.asyncio import (
async_sessionmaker,
create_async_engine,
)
from sqlalchemy.pool import AsyncAdaptedQueuePool
from sqlalchemy.util import await_
from src.config.settings import Database
@@ -47,6 +49,43 @@ class BoundedCloseConnection(asyncpg.Connection):
transport.abort()
class CountingQueuePool(AsyncAdaptedQueuePool):
"""Пул engine со счётом запросов соединения, которые сейчас ждут, и
отказов по сроку (design change `job-trace-propagation`, решение 10).
Публичный `Pool.connect()` — ожидание места, открытие соединения и
проверка при выдаче; числа ожидающих `QueuePool` не отдаёт. `dispose()`
создаёт новый пул того же класса (`recreate`), поэтому счёт — свойство
пула, а не подмена метода экземпляра. Фабрика о телеметрии не знает: числа
читают метрики `db.client.connection.*`. Опирается на `Pool.connect()` и
`QueuePool`, SQLAlchemy закреплён `<2.2`; смену ловит `make
service_test_db` (`test_pool_counts_*`).
"""
def __init__(self, *args: Any, **kwargs: Any) -> None:
super().__init__(*args, **kwargs)
self._pending = 0
self._timeouts = 0
def connect(self) -> Any:
self._pending += 1
try:
return super().connect()
except sa_exc.TimeoutError:
self._timeouts += 1
raise
finally:
self._pending -= 1
def pending(self) -> int:
"""Запросы соединения, которые сейчас ждут места или открытия."""
return self._pending
def timeouts(self) -> int:
"""Отказы по сроку ожидания пула с создания пула."""
return self._timeouts
def _ping_once(dbapi_connection: Any) -> bool:
"""Проверка соединения при выдаче одним обменом `;`.
@@ -80,6 +119,7 @@ def create_engine(database: Database) -> AsyncEngine:
)
engine = create_async_engine(
database.url,
poolclass=CountingQueuePool,
pool_size=database.pool_size,
max_overflow=database.max_overflow,
pool_timeout=database.pool_timeout_seconds,
+15
View File
@@ -144,6 +144,17 @@ class AttachmentJob(Base):
"attempt_base BETWEEN 0 AND attempt",
name="attempt_base",
),
# контекст W3C загрузки (design change job-trace-propagation, решение
# 4): шаблон contracts/jobs.schema.json; в ревизии — NOT VALID
CheckConstraint(
"traceparent ~ '^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$'",
name="traceparent",
),
CheckConstraint(
"tracestate IS NULL OR (traceparent IS NOT NULL "
"AND char_length(tracestate) BETWEEN 1 AND 512)",
name="tracestate",
),
# Autogenerate условие и выражение не видит; в ревизии — CONCURRENTLY.
# Запросы пишут state константой, иначе общий план подготовленного
# выражения индекс не возьмёт
@@ -202,6 +213,10 @@ class AttachmentJob(Base):
finished_at: Mapped[datetime | None] = mapped_column(
DateTime(timezone=True),
)
# контекст server span загрузки; NULL — строка прежней версии или реплика
# без телеметрии (design change job-trace-propagation, решение 4)
traceparent: Mapped[str | None] = mapped_column(Text)
tracestate: Mapped[str | None] = mapped_column(Text)
class AttachmentJobReplay(Base):
+7
View File
@@ -20,6 +20,7 @@ from structlog.typing import EventDict, WrappedLogger
from src.config import settings
from src.utils.constants import (
DB_POOL_LOGGER,
TELEMETRY_SDK_LOG_WINDOW_SECONDS,
TELEMETRY_SDK_LOGGER_PREFIX,
)
@@ -280,6 +281,12 @@ def configure_logger() -> None:
# протокола с телами сообщений и строку подключения
"aio_pika": {"level": "WARNING"},
"aiormq": {"level": "WARNING"},
# пул engine (design change job-trace-propagation, решение
# 10): SQLAlchemy называет логгер пула по его классу, а класс
# живёт в src — без этой строки «Pool recreating» и «Pool
# disposed» шли бы INFO, как у логгера src; уровень — прежний,
# как у пула SQLAlchemy под root
DB_POOL_LOGGER: {"level": "WARNING"},
},
},
)
+20 -4
View File
@@ -1,15 +1,16 @@
"""Телеметрия процессов API и worker (design change `otel-telemetry`).
"""Телеметрия процессов API, worker и relay (design change `otel-telemetry`,
`job-trace-propagation`).
Правила — `.claude/rules/telemetry.md`. Без включённой телеметрии все вызовы
ничего не делают: ни провайдеров, ни хуков журнала, ни обращений к Collector.
ничего не делают: ни провайдеров, ни хуков журнала, ни обращений к Collector,
ни модулей SDK в памяти (их загружает только `core.start()`).
"""
from src.infra.telemetry.core import (
Exporters,
JobObservation,
begin_shutdown,
child_span,
consumer_span,
current_trace_context,
finish_request,
http_method,
is_enabled,
@@ -21,21 +22,36 @@ from src.infra.telemetry.core import (
)
from src.infra.telemetry.db import commit_span, instrument_engine
from src.infra.telemetry.logs import install_log_hooks, remove_log_hooks
from src.infra.telemetry.messaging import (
JobObservation,
consumer_span,
producer_span,
)
from src.infra.telemetry.metrics import (
WorkerLoad,
observe_queue,
observe_worker,
)
from src.infra.telemetry.setup import start_process_telemetry
__all__ = [
"Exporters",
"JobObservation",
"WorkerLoad",
"begin_shutdown",
"child_span",
"commit_span",
"consumer_span",
"current_trace_context",
"finish_request",
"http_method",
"install_log_hooks",
"instrument_engine",
"is_enabled",
"mark_error",
"observe_queue",
"observe_worker",
"producer_span",
"remove_log_hooks",
"remove_otel_environment",
"server_span",
+112
View File
@@ -0,0 +1,112 @@
"""CPU и память контейнера по его cgroup v2 изнутри (design change
`job-trace-propagation`, решение 12).
Без сокета Docker: доступ к API Docker равен root на ВМ. Файлы читает callback
сбора метрик (микросекунды), корень cgroup — параметр, по умолчанию
`CGROUP_ROOT`: быстрые тесты дают временный каталог. У worker cgroup включает
процессы обработки. Значение `max` в `cpu.max` и `memory.max` — предела нет,
точки нет.
"""
from collections.abc import Iterable
from pathlib import Path
from typing import Any
from opentelemetry.metrics import Meter, Observation
from src.utils.constants import (
METRIC_CONTAINER_CPU_LIMIT,
METRIC_CONTAINER_CPU_TIME,
METRIC_CONTAINER_MEMORY_LIMIT,
METRIC_CONTAINER_MEMORY_USAGE,
)
_USEC = 1_000_000
_NO_LIMIT = "max"
def _read(path: Path) -> str | None:
try:
return path.read_text().strip()
except (OSError, ValueError):
return None
def cpu_seconds(root: Path) -> float | None:
"""`usage_usec` из `cpu.stat` в секундах."""
text = _read(root / "cpu.stat")
if text is None:
return None
for line in text.splitlines():
name, _, value = line.partition(" ")
if name == "usage_usec" and value.strip().isdigit():
return int(value) / _USEC
return None
def memory_bytes(root: Path) -> int | None:
text = _read(root / "memory.current")
return int(text) if text is not None and text.isdigit() else None
def cpu_limit(root: Path) -> float | None:
"""Квота к периоду `cpu.max` в ядрах; `max` — предела нет."""
text = _read(root / "cpu.max")
if text is None:
return None
parts = text.split()
if len(parts) != 2 or parts[0] == _NO_LIMIT:
return None
try:
quota, period = int(parts[0]), int(parts[1])
except ValueError:
return None
return quota / period if period > 0 else None
def memory_limit(root: Path) -> int | None:
text = _read(root / "memory.max")
if text is None or text == _NO_LIMIT or not text.isdigit():
return None
return int(text)
def available(root: Path) -> bool:
"""Метрики контейнера есть, если читаются `cpu.stat` и
`memory.current`."""
return cpu_seconds(root) is not None and memory_bytes(root) is not None
def _observe(value: Any) -> Iterable[Observation]:
return [] if value is None else [Observation(value)]
def register(meter: Meter, *, root: Path) -> None:
"""Наблюдаемые инструменты контейнера; вызывающий проверил
`available`."""
meter.create_observable_counter(
METRIC_CONTAINER_CPU_TIME,
callbacks=[
lambda _options: _observe(cpu_seconds(root)),
],
unit="s",
description="CPU time of the container",
)
meter.create_observable_up_down_counter(
METRIC_CONTAINER_MEMORY_USAGE,
callbacks=[lambda _options: _observe(memory_bytes(root))],
unit="By",
description="Memory usage of the container",
)
meter.create_observable_up_down_counter(
METRIC_CONTAINER_CPU_LIMIT,
callbacks=[lambda _options: _observe(cpu_limit(root))],
unit="{cpu}",
description="CPU limit of the container",
)
meter.create_observable_up_down_counter(
METRIC_CONTAINER_MEMORY_LIMIT,
callbacks=[lambda _options: _observe(memory_limit(root))],
unit="By",
description="Memory limit of the container",
)
+114 -254
View File
@@ -1,12 +1,13 @@
"""Запуск и закрытие SDK OpenTelemetry, span и метрики процесса.
"""Запуск и закрытие SDK OpenTelemetry, span запроса и хранилищ.
Design change `otel-telemetry`, решения 4, 8–13; правила —
`.claude/rules/telemetry.md`. Провайдеры глобальными не ставятся: их держит
состояние модуля, а вызовы ниже при выключенной телеметрии ничего не делают.
SDK собирается только из `[telemetry]`: переменные `OTEL_*` удаляются из
окружения до создания провайдеров (`OTEL_SDK_DISABLED` провайдеры читают в
конструкторе), ресурс — конструктором без детекторов, у всех параметров
явные значения, `atexit` SDK выключен.
Design change `otel-telemetry`, решения 4, 8–13, и `job-trace-propagation`,
решения 5, 7; правила — `.claude/rules/telemetry.md`. Провайдеры глобальными
не ставятся: их держит состояние модуля, а вызовы ниже при выключенной
телеметрии ничего не делают. Модуль импортирует только `opentelemetry-api`:
SDK, экспортёр и `requests` загружает `start()` (модуль `sdk`), поэтому
процесс без телеметрии их в памяти не держит. Переменные `OTEL_*` вызывающий
удаляет из окружения до `start()` (`OTEL_SDK_DISABLED` провайдеры читают в
конструкторе).
"""
import asyncio
@@ -14,93 +15,45 @@ import os
import threading
from collections.abc import Iterator, Mapping, Sequence
from contextlib import contextmanager, suppress
from dataclasses import dataclass, field
from typing import Any
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any
# транспорт экспортёров OTLP/HTTP (зависимость opentelemetry-exporter-otlp-
# proto-http): своя сессия без окружения
import requests
from opentelemetry import trace
from opentelemetry.context import Context
from opentelemetry.exporter.otlp.proto.http import Compression
from opentelemetry.exporter.otlp.proto.http._log_exporter import (
OTLPLogExporter,
)
from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
OTLPMetricExporter,
)
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
OTLPSpanExporter,
)
from opentelemetry.sdk._logs import Logger as OtelLogger
from opentelemetry.sdk._logs import LoggerProvider, LogRecordLimits
from opentelemetry.sdk._logs.export import (
BatchLogRecordProcessor,
LogRecordExporter,
)
from opentelemetry.sdk.metrics import (
AlwaysOffExemplarFilter,
Counter,
Histogram,
MeterProvider,
ObservableCounter,
ObservableGauge,
ObservableUpDownCounter,
UpDownCounter,
)
from opentelemetry.sdk.metrics.export import (
AggregationTemporality,
MetricReader,
PeriodicExportingMetricReader,
)
from opentelemetry.sdk.metrics.view import (
ExplicitBucketHistogramAggregation,
View,
)
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import SpanLimits, TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
from opentelemetry.trace import Span, SpanKind, Status, StatusCode, Tracer
from opentelemetry.trace.propagation.tracecontext import (
TraceContextTextMapPropagator,
)
from src.config.settings import Telemetry as TelemetrySettings
from src.schemas.dataclasses import TraceContextDTO
from src.utils.constants import (
ATTR_ERROR_TYPE,
ATTR_HTTP_METHOD,
ATTR_HTTP_ROUTE,
ATTR_HTTP_STATUS,
ATTR_JOB_OUTCOME,
ATTR_JOB_TYPE,
ATTR_REQUEST_ID,
HTTP_DURATION_BUCKETS,
HTTP_KNOWN_METHODS,
HTTP_OTHER_METHOD,
JOB_DURATION_BUCKETS,
METRIC_HTTP_SERVER_DURATION,
METRIC_JOB_DURATION,
METRIC_JOB_TIME_TO_READY,
SERVICE_VERSION,
TELEMETRY_LOG_ATTRIBUTE_LENGTH,
TELEMETRY_LOGS_PATH,
TELEMETRY_MAX_ATTRIBUTES,
TELEMETRY_METRICS_PATH,
TELEMETRY_SCOPE,
TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
TELEMETRY_TRACES_PATH,
TRACE_HEADER_TRACEPARENT,
TRACE_HEADER_TRACESTATE,
)
if TYPE_CHECKING:
from opentelemetry.metrics import Meter
from opentelemetry.sdk._logs import LogRecordExporter
from opentelemetry.sdk.metrics.export import MetricReader
from opentelemetry.sdk.trace.export import SpanExporter
_OTEL_ENV_PREFIX = "OTEL_"
# все инструменты — cumulative: Prometheus забирает накопленное (решение 3)
_CUMULATIVE = dict.fromkeys(
(
Counter,
UpDownCounter,
Histogram,
ObservableCounter,
ObservableUpDownCounter,
ObservableGauge,
),
AggregationTemporality.CUMULATIVE,
)
# только W3C Trace Context, без baggage и без глобального propagator
# (решение 5): переносится контекст трассы, а не данные
PROPAGATOR = TraceContextTextMapPropagator()
@dataclass(frozen=True, slots=True)
@@ -108,20 +61,20 @@ class Exporters:
"""Получатели сигналов вместо OTLP — только для быстрых тестов
(in-memory экспортёры SDK)."""
spans: SpanExporter
metrics: MetricReader
logs: LogRecordExporter
spans: "SpanExporter"
metrics: "MetricReader"
logs: "LogRecordExporter"
@dataclass(slots=True)
class _State:
tracer: Tracer
otel_logger: OtelLogger
meter: "Meter"
otel_logger: Any
http_duration: Any
job_duration: Any
tracer_provider: TracerProvider
meter_provider: MeterProvider
logger_provider: LoggerProvider
time_to_ready: Any
providers: Any
_state: _State | None = None
@@ -149,7 +102,8 @@ def start(
config: TelemetrySettings,
exporters: Exporters | None = None,
) -> bool:
"""Провайдеры трасс, метрик и логов процесса. Выключено — ничего.
"""Провайдеры трасс, метрик и логов процесса. Выключено — ничего, и SDK
не загружается.
Вызывающий до этого удаляет `OTEL_*` (`remove_otel_environment`) и
пишет `warning`; хуки журнала ставит `src.infra.telemetry.logs`."""
@@ -158,84 +112,30 @@ def start(
return True
if not config.enabled and exporters is None:
return False
resource = Resource(
{
# SDK — только здесь (design change job-trace-propagation, решение 7)
from src.infra.telemetry import sdk
providers = sdk.build(
resource={
"service.name": service_name,
"service.version": SERVICE_VERSION,
"service.instance.id": instance_id,
"deployment.environment.name": config.environment,
},
config=config,
exporters=exporters,
)
if exporters is None:
exporters = _otlp_exporters(config)
timeout_ms = config.export_timeout_seconds * 1000
delay_ms = config.schedule_delay_seconds * 1000
tracer_provider = TracerProvider(
sampler=ALWAYS_ON,
resource=resource,
shutdown_on_exit=False,
span_limits=SpanLimits(
max_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_events=TELEMETRY_MAX_ATTRIBUTES,
max_links=TELEMETRY_MAX_ATTRIBUTES,
max_span_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_event_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_link_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
max_span_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
),
meter = providers.meter_provider.get_meter(
TELEMETRY_SCOPE,
SERVICE_VERSION,
)
tracer_provider.add_span_processor(
BatchSpanProcessor(
exporters.spans,
max_queue_size=config.max_queue_size,
schedule_delay_millis=delay_ms,
max_export_batch_size=config.max_export_batch_size,
export_timeout_millis=timeout_ms,
),
)
meter_provider = MeterProvider(
metric_readers=[exporters.metrics],
resource=resource,
exemplar_filter=AlwaysOffExemplarFilter(),
shutdown_on_exit=False,
views=[
View(
instrument_name=METRIC_HTTP_SERVER_DURATION,
aggregation=ExplicitBucketHistogramAggregation(
boundaries=HTTP_DURATION_BUCKETS,
),
),
View(
instrument_name=METRIC_JOB_DURATION,
aggregation=ExplicitBucketHistogramAggregation(
boundaries=JOB_DURATION_BUCKETS,
),
),
],
)
logger_provider = LoggerProvider(
resource=resource,
shutdown_on_exit=False,
log_record_limits=LogRecordLimits(
max_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_attribute_length=TELEMETRY_LOG_ATTRIBUTE_LENGTH,
),
)
logger_provider.add_log_record_processor(
BatchLogRecordProcessor(
exporters.logs,
schedule_delay_millis=delay_ms,
max_export_batch_size=config.max_export_batch_size,
export_timeout_millis=timeout_ms,
max_queue_size=config.max_queue_size,
),
)
meter = meter_provider.get_meter(TELEMETRY_SCOPE, SERVICE_VERSION)
_state = _State(
tracer=tracer_provider.get_tracer(TELEMETRY_SCOPE, SERVICE_VERSION),
otel_logger=logger_provider.get_logger(
tracer=providers.tracer_provider.get_tracer(
TELEMETRY_SCOPE,
SERVICE_VERSION,
),
meter=meter,
otel_logger=providers.logger_provider.get_logger(
TELEMETRY_SCOPE,
SERVICE_VERSION,
),
@@ -249,58 +149,16 @@ def start(
unit="s",
description="Duration of job deliveries handled by the worker",
),
tracer_provider=tracer_provider,
meter_provider=meter_provider,
logger_provider=logger_provider,
time_to_ready=meter.create_histogram(
METRIC_JOB_TIME_TO_READY,
unit="s",
description="Time from accepted upload to ready attachment",
),
providers=providers,
)
return True
def _export_session() -> requests.Session:
"""Сессия отправки без окружения: `HTTP(S)_PROXY`, `NO_PROXY`, `.netrc`
и `REQUESTS_CA_BUNDLE` на неё не действуют — данные идут только по адресу
`[telemetry]` (verify S5, как с `OTEL_*`, решение 8)."""
session = requests.Session()
session.trust_env = False
return session
def _otlp_exporters(config: TelemetrySettings) -> Exporters:
"""OTLP/HTTP protobuf только из `[telemetry]`: адрес, срок, без
заголовков и сжатия, своя сессия без прокси окружения."""
timeout = config.export_timeout_seconds
endpoint = config.otlp_endpoint
return Exporters(
spans=OTLPSpanExporter(
endpoint=endpoint + TELEMETRY_TRACES_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
session=_export_session(),
),
metrics=PeriodicExportingMetricReader(
OTLPMetricExporter(
endpoint=endpoint + TELEMETRY_METRICS_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
preferred_temporality=_CUMULATIVE,
session=_export_session(),
),
export_interval_millis=config.metric_export_interval_seconds
* 1000,
export_timeout_millis=timeout * 1000,
),
logs=OTLPLogExporter(
endpoint=endpoint + TELEMETRY_LOGS_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
session=_export_session(),
),
)
def begin_shutdown() -> list[threading.Thread]:
"""Закрытие провайдеров в daemon-потоках, по одному на сигнал: при
замороженном Collector каждый ждёт свой срок отправки, а записи журнала
@@ -318,9 +176,9 @@ def begin_shutdown() -> list[threading.Thread]:
daemon=True,
)
for name, provider in (
("logs", state.logger_provider),
("traces", state.tracer_provider),
("metrics", state.meter_provider),
("logs", state.providers.logger_provider),
("traces", state.providers.tracer_provider),
("metrics", state.providers.meter_provider),
)
]
for thread in threads:
@@ -449,58 +307,49 @@ def finish_request(
state.http_duration.record(duration_seconds, attributes)
@dataclass(slots=True)
class JobObservation:
"""Учёт одной доставки worker: исход — атрибут span и метка histogram."""
span: Span | None
job_type: str
recorded: bool = field(default=False)
def finish(
self,
*,
outcome: str,
duration_seconds: float,
error: BaseException | None = None,
) -> None:
state = _state
if state is None or self.recorded:
return
self.recorded = True
if self.span is not None:
self.span.set_attribute(ATTR_JOB_OUTCOME, outcome)
if error is not None:
mark_error(self.span, error)
state.job_duration.record(
duration_seconds,
{ATTR_JOB_TYPE: self.job_type, ATTR_JOB_OUTCOME: outcome},
)
def trace_headers(context: Context | None = None) -> dict[str, str]:
"""`traceparent` и непустой `tracestate` контекста (по умолчанию —
текущего); невалидный span — пусто."""
carrier: dict[str, str] = {}
PROPAGATOR.inject(carrier, context=context)
return carrier
@contextmanager
def consumer_span(*, queue: str, job_type: str) -> Iterator[JobObservation]:
"""Span `CONSUMER` доставки (решение 11), корень трассы задания: контекст
из сообщения переносит change 2. Исход и длительность называет
`JobObservation.finish`."""
state = _state
if state is None:
yield JobObservation(span=None, job_type=job_type)
return
with state.tracer.start_as_current_span(
f"process {queue}",
context=Context(),
kind=SpanKind.CONSUMER,
attributes={
"messaging.system": "rabbitmq",
"messaging.destination.name": queue,
"messaging.operation.type": "process",
ATTR_JOB_TYPE: job_type,
},
record_exception=False,
set_status_on_exception=False,
) as span:
yield JobObservation(span=span, job_type=job_type)
def to_trace_context(carrier: Mapping[str, str]) -> TraceContextDTO | None:
traceparent = carrier.get(TRACE_HEADER_TRACEPARENT)
if not traceparent:
return None
return TraceContextDTO(
traceparent=traceparent,
tracestate=carrier.get(TRACE_HEADER_TRACESTATE) or None,
)
def to_carrier(trace_context: TraceContextDTO) -> dict[str, str]:
carrier = {TRACE_HEADER_TRACEPARENT: trace_context.traceparent}
if trace_context.tracestate:
carrier[TRACE_HEADER_TRACESTATE] = trace_context.tracestate
return carrier
def remote_context(trace_context: TraceContextDTO | None) -> Context | None:
"""Контекст удалённого родителя из сохранённого значения; `None` — нет
значения или оно не по W3C (новая трасса, а не ошибка)."""
if trace_context is None:
return None
context = PROPAGATOR.extract(to_carrier(trace_context), context=Context())
if not trace.get_current_span(context).get_span_context().is_valid:
return None
return context
def current_trace_context() -> TraceContextDTO | None:
"""Контекст текущего валидного span — server span загрузки — для
задания (решение 4); невыбранный сохраняется с флагом `00`. Без
телеметрии или вне span — `None`."""
if _state is None:
return None
return to_trace_context(trace_headers())
def tracer() -> Tracer | None:
@@ -508,6 +357,17 @@ def tracer() -> Tracer | None:
return None if state is None else state.tracer
def otel_logger() -> OtelLogger | None:
def meter() -> "Meter | None":
state = _state
return None if state is None else state.meter
def otel_logger() -> Any:
state = _state
return None if state is None else state.otel_logger
def job_histograms() -> tuple[Any, Any] | None:
"""Histogram длительности доставки и времени до готовности."""
state = _state
return None if state is None else (state.job_duration, state.time_to_ready)
+19 -3
View File
@@ -17,7 +17,8 @@ from sqlalchemy import event
from sqlalchemy.engine import ExceptionContext
from sqlalchemy.ext.asyncio import AsyncEngine
from src.infra.telemetry import core
from src.config import settings
from src.infra.telemetry import core, metrics
DB_SYSTEM = "postgresql"
# атрибут контекста выполнения со span запроса
@@ -41,10 +42,25 @@ def operation_name(statement: str) -> str:
return words[0].upper() if words else "QUERY"
def instrument_engine(engine: AsyncEngine) -> None:
"""Слушатели span на engine процесса; телеметрия выключена — ничего."""
def instrument_engine(
engine: AsyncEngine,
*,
max_overflow: int | None = None,
) -> None:
"""Слушатели span и метрики пула (`db.client.connection.*`, design change
`job-trace-propagation`, решение 10) на engine процесса; предел пула —
его размер и `max_overflow` (по умолчанию `[database]`). Телеметрия
выключена — ничего."""
if not core.is_enabled():
return
metrics.observe_pool(
engine,
max_overflow=(
settings.database.max_overflow
if max_overflow is None
else max_overflow
),
)
sync_engine = engine.sync_engine
base = db_attributes(sync_engine.url)
+200
View File
@@ -0,0 +1,200 @@
"""Span брокера: producer публикации relay и consumer доставки worker.
Design change `job-trace-propagation`, решения 1–3, 8, 13. Контекст W3C
загрузки сохранён в задании; relay открывает span `PRODUCER` дочерним к нему и
кладёт в заголовки сообщения контекст этого span, worker делает span
`CONSUMER` дочерним к контексту из заголовков и ставит link на него
(semantic conventions messaging, обработка одного сообщения). Без контекста
— ни span producer, ни заголовков, а consumer span — корень трассы, как на
уровне 3 (решение 6). Атрибуты — значения enum, без `id` и текста ошибок.
"""
from collections.abc import Iterator
from contextlib import contextmanager
from dataclasses import dataclass, field
from opentelemetry import trace
from opentelemetry.context import Context
from opentelemetry.trace import Link, Span, SpanKind
from src.infra.telemetry import core
from src.schemas.dataclasses import (
JobDeliveryResultDTO,
JobPublicationDTO,
TraceContextDTO,
)
from src.utils.constants import (
ATTR_JOB_ATTEMPT,
ATTR_JOB_ERROR_CODE,
ATTR_JOB_OUTCOME,
ATTR_JOB_REASON,
ATTR_JOB_REDELIVERED,
ATTR_JOB_REPLAYED,
ATTR_JOB_RETRY_REASON,
ATTR_JOB_TYPE,
ATTR_MESSAGING_DESTINATION,
ATTR_MESSAGING_OPERATION_NAME,
ATTR_MESSAGING_OPERATION_TYPE,
ATTR_MESSAGING_SYSTEM,
MESSAGING_OPERATION_PROCESS,
MESSAGING_OPERATION_PUBLISH,
MESSAGING_SYSTEM,
)
# messaging.operation.type semantic conventions
_OPERATION_SEND = "send"
_OPERATION_PROCESS = "process"
def _messaging_attributes(
*,
queue: str,
operation_type: str,
operation_name: str,
job_type: str,
) -> dict[str, str]:
return {
ATTR_MESSAGING_SYSTEM: MESSAGING_SYSTEM,
ATTR_MESSAGING_DESTINATION: queue,
ATTR_MESSAGING_OPERATION_TYPE: operation_type,
ATTR_MESSAGING_OPERATION_NAME: operation_name,
ATTR_JOB_TYPE: job_type,
}
@contextmanager
def producer_span(
*,
queue: str,
job_type: str,
publication: JobPublicationDTO,
) -> Iterator[dict[str, str]]:
"""Span `PRODUCER` `publish <очередь>` публикации под сохранённым
контекстом задания; отдаёт заголовки сообщения. Span заканчивается при
выходе (после подтверждения брокером); ошибка и отмена — `ERROR` и класс.
Нет контекста или он не по W3C — пусто и без span: проходы relay трасс не
начинают. Телеметрия выключена — сохранённый контекст как есть: цепочка
API → worker не рвётся."""
parent = core.remote_context(publication.trace_context)
tracer = core.tracer()
if parent is None:
yield {}
return
if tracer is None:
yield core.to_carrier(publication.trace_context)
return
attributes: dict[str, str | int | bool] = {
**_messaging_attributes(
queue=queue,
operation_type=_OPERATION_SEND,
operation_name=MESSAGING_OPERATION_PUBLISH,
job_type=job_type,
),
ATTR_JOB_ATTEMPT: publication.attempt,
ATTR_JOB_REPLAYED: publication.replayed,
}
if publication.retry_reason:
attributes[ATTR_JOB_RETRY_REASON] = publication.retry_reason
span = tracer.start_span(
f"{MESSAGING_OPERATION_PUBLISH} {queue}",
context=parent,
kind=SpanKind.PRODUCER,
attributes=attributes,
record_exception=False,
set_status_on_exception=False,
)
try:
yield core.trace_headers(trace.set_span_in_context(span))
except BaseException as e:
core.mark_error(span, e)
raise
finally:
span.end()
@dataclass(slots=True)
class JobObservation:
"""Учёт одной доставки worker: итог — атрибуты span, метка histogram
длительности и, у `ready` без replay, точка времени до готовности."""
span: Span | None
job_type: str
recorded: bool = field(default=False)
def finish(
self,
*,
result: JobDeliveryResultDTO,
duration_seconds: float,
error: BaseException | None = None,
) -> None:
histograms = core.job_histograms()
if histograms is None or self.recorded:
return
self.recorded = True
outcome = result.outcome.value
if self.span is not None:
self.span.set_attribute(ATTR_JOB_OUTCOME, outcome)
if result.attempt is not None:
self.span.set_attribute(ATTR_JOB_ATTEMPT, result.attempt)
if result.reason is not None:
self.span.set_attribute(ATTR_JOB_REASON, result.reason.value)
if result.error_code is not None:
self.span.set_attribute(
ATTR_JOB_ERROR_CODE,
result.error_code.value,
)
if error is not None:
core.mark_error(self.span, error)
duration, time_to_ready = histograms
duration.record(
duration_seconds,
{ATTR_JOB_TYPE: self.job_type, ATTR_JOB_OUTCOME: outcome},
)
if result.time_to_ready_seconds is not None:
time_to_ready.record(
result.time_to_ready_seconds,
{ATTR_JOB_TYPE: self.job_type},
)
@contextmanager
def consumer_span(
*,
queue: str,
job_type: str,
parent: TraceContextDTO | None = None,
redelivered: bool = False,
) -> Iterator[JobObservation]:
"""Span `CONSUMER` `process <очередь>` доставки (решения 2, 11): дочерний
к контексту из заголовков сообщения и с link на него; без контекста или с
неверным — корень трассы. Под невыбранным родителем span не
записывается, исход и метрики те же. Итог называет
`JobObservation.finish`."""
tracer = core.tracer()
if tracer is None:
yield JobObservation(span=None, job_type=job_type)
return
remote = core.remote_context(parent)
links = []
if remote is not None:
links.append(Link(trace.get_current_span(remote).get_span_context()))
with tracer.start_as_current_span(
f"{MESSAGING_OPERATION_PROCESS} {queue}",
context=remote if remote is not None else Context(),
kind=SpanKind.CONSUMER,
links=links,
attributes={
**_messaging_attributes(
queue=queue,
operation_type=_OPERATION_PROCESS,
operation_name=MESSAGING_OPERATION_PROCESS,
job_type=job_type,
),
ATTR_JOB_REDELIVERED: redelivered,
},
record_exception=False,
set_status_on_exception=False,
) as span:
yield JobObservation(span=span, job_type=job_type)
+204
View File
@@ -0,0 +1,204 @@
"""Наблюдаемые метрики уровня 4: пул PostgreSQL, насыщение worker, очередь.
Design change `job-trace-propagation`, решения 9–11, 13. Значения читает
callback сбора метрик в потоке экспорта, пишет цикл событий: гонка безвредна
(целые, на сбор ± 1). Телеметрия выключена — регистрации нет.
"""
from collections.abc import Callable, Iterable
from dataclasses import dataclass
from datetime import timedelta
from typing import Any
from opentelemetry.metrics import CallbackOptions, Observation
from src.infra.telemetry import core
from src.schemas.dataclasses import QueueSnapshotDTO
from src.utils.constants import (
ATTR_DB_CONNECTION_STATE,
ATTR_DB_POOL_NAME,
ATTR_MESSAGING_DESTINATION,
ATTR_QUEUE_STAGE,
DB_CONNECTION_STATE_IDLE,
DB_CONNECTION_STATE_USED,
METRIC_DB_CONNECTION_COUNT,
METRIC_DB_CONNECTION_MAX,
METRIC_DB_CONNECTION_PENDING,
METRIC_DB_CONNECTION_TIMEOUTS,
METRIC_QUEUE_DEPTH,
METRIC_QUEUE_OLDEST_AGE,
METRIC_WORKER_BUSY,
METRIC_WORKER_CAPACITY,
METRIC_WORKER_WAITING,
QUEUE_SNAPSHOT_STALE_SECONDS,
QUEUE_STAGE_OUTBOX,
QUEUE_STAGE_PROCESSING,
QUEUE_STAGE_PUBLISHED,
QUEUE_STAGE_SCHEDULED,
)
from src.utils.utc import utcnow
def pool_name(engine_url: Any) -> str:
"""Имя пула по semantic conventions: `server.address:server.port/
db.namespace`."""
port = "" if engine_url.port is None else f":{engine_url.port}"
return f"{engine_url.host or ''}{port}/{engine_url.database or ''}"
def observe_pool(engine: Any, *, max_overflow: int) -> None:
"""`db.client.connection.*` пула engine (решение 10): каждый сбор читает
текущий `engine.sync_engine.pool` — `dispose()` создаёт новый пул того же
класса. Ожидающие и отказы по сроку — у `CountingQueuePool`."""
meter = core.meter()
if meter is None:
return
sync_engine = engine.sync_engine
attributes = {ATTR_DB_POOL_NAME: pool_name(sync_engine.url)}
def counts(_options: CallbackOptions) -> Iterable[Observation]:
pool = sync_engine.pool
return [
Observation(
pool.checkedout(),
{
**attributes,
ATTR_DB_CONNECTION_STATE: DB_CONNECTION_STATE_USED,
},
),
Observation(
pool.checkedin(),
{
**attributes,
ATTR_DB_CONNECTION_STATE: DB_CONNECTION_STATE_IDLE,
},
),
]
def limit(_options: CallbackOptions) -> Iterable[Observation]:
return [
Observation(sync_engine.pool.size() + max_overflow, attributes),
]
def pending(_options: CallbackOptions) -> Iterable[Observation]:
read = getattr(sync_engine.pool, "pending", None)
return [] if read is None else [Observation(read(), attributes)]
def timeouts(_options: CallbackOptions) -> Iterable[Observation]:
read = getattr(sync_engine.pool, "timeouts", None)
return [] if read is None else [Observation(read(), attributes)]
meter.create_observable_up_down_counter(
METRIC_DB_CONNECTION_COUNT,
callbacks=[counts],
unit="{connection}",
description="Connections of the pool by state",
)
meter.create_observable_up_down_counter(
METRIC_DB_CONNECTION_MAX,
callbacks=[limit],
unit="{connection}",
description="Maximum connections of the pool",
)
meter.create_observable_up_down_counter(
METRIC_DB_CONNECTION_PENDING,
callbacks=[pending],
unit="{request}",
description="Requests waiting for a pool connection",
)
meter.create_observable_counter(
METRIC_DB_CONNECTION_TIMEOUTS,
callbacks=[timeouts],
unit="{timeout}",
description="Pool checkouts that timed out",
)
@dataclass(slots=True)
class WorkerLoad:
"""Счётчики мест конкуренции worker (решение 11): `waiting` — доставки до
входа в место, `busy` — внутри. Пишет `_handle` worker."""
busy: int = 0
waiting: int = 0
def observe_worker(*, capacity: int, load: WorkerLoad) -> None:
meter = core.meter()
if meter is None:
return
meter.create_observable_up_down_counter(
METRIC_WORKER_BUSY,
callbacks=[lambda _options: [Observation(load.busy)]],
unit="{delivery}",
description="Deliveries occupying a concurrency slot",
)
meter.create_observable_up_down_counter(
METRIC_WORKER_CAPACITY,
callbacks=[lambda _options: [Observation(capacity)]],
unit="{delivery}",
description="Concurrency slots of the worker",
)
meter.create_observable_up_down_counter(
METRIC_WORKER_WAITING,
callbacks=[lambda _options: [Observation(load.waiting)]],
unit="{delivery}",
description="Received deliveries waiting for a slot",
)
def queue_observations(
snapshot: QueueSnapshotDTO | None,
*,
queue: str,
) -> tuple[list[Observation], list[Observation]]:
"""Глубина по стадиям и возраст старейшего из последнего снимка; снимок
старше `QUEUE_SNAPSHOT_STALE_SECONDS` или его нет — ничего (решение 9)."""
if snapshot is None or utcnow() - snapshot.taken_at > timedelta(
seconds=QUEUE_SNAPSHOT_STALE_SECONDS,
):
return [], []
base = {ATTR_MESSAGING_DESTINATION: queue}
depth = [
Observation(value, {**base, ATTR_QUEUE_STAGE: stage})
for stage, value in (
(QUEUE_STAGE_SCHEDULED, snapshot.scheduled),
(QUEUE_STAGE_OUTBOX, snapshot.outbox),
(QUEUE_STAGE_PUBLISHED, snapshot.published),
(QUEUE_STAGE_PROCESSING, snapshot.processing),
)
]
age = 0.0
if snapshot.oldest_created_at is not None:
age = max(
0.0,
(snapshot.taken_at - snapshot.oldest_created_at).total_seconds(),
)
return depth, [Observation(age, base)]
def observe_queue(
*,
queue: str,
latest: Callable[[], QueueSnapshotDTO | None],
) -> None:
"""Gauge глубины и возраста очереди relay по последнему снимку."""
meter = core.meter()
if meter is None:
return
meter.create_observable_gauge(
METRIC_QUEUE_DEPTH,
callbacks=[
lambda _options: queue_observations(latest(), queue=queue)[0],
],
unit="{job}",
description="Unfinished jobs by stage",
)
meter.create_observable_gauge(
METRIC_QUEUE_OLDEST_AGE,
callbacks=[
lambda _options: queue_observations(latest(), queue=queue)[1],
],
unit="s",
description="Age of the oldest unfinished job since it was accepted",
)
+222
View File
@@ -0,0 +1,222 @@
"""Сборка провайдеров SDK OpenTelemetry и экспортёров OTLP/HTTP.
Единственный модуль пакета, который импортирует SDK, экспортёр и `requests`
(design change `job-trace-propagation`, решение 7): его импортирует только
`core.start()`, поэтому процесс с выключенной телеметрией, уборщик и команда
replay модулей SDK, protobuf и HTTP-клиента экспортёра не загружают. Остальные
модули пакета — только `opentelemetry-api`.
Всё — из `[telemetry]` (design change `otel-telemetry`, решение 8): ресурс
конструктором без детекторов, у параметров явные значения, `atexit` SDK
выключен. Sampler — `ParentBased(ALWAYS_ON)` (решение 5): корни выбираются
всегда, удалённый родитель из задания передаёт свой флаг выборки.
"""
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Any
# транспорт экспортёров OTLP/HTTP (зависимость opentelemetry-exporter-otlp-
# proto-http): своя сессия без окружения
import requests
from opentelemetry.exporter.otlp.proto.http import Compression
from opentelemetry.exporter.otlp.proto.http._log_exporter import (
OTLPLogExporter,
)
from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
OTLPMetricExporter,
)
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
OTLPSpanExporter,
)
from opentelemetry.sdk._logs import LoggerProvider, LogRecordLimits
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.metrics import (
AlwaysOffExemplarFilter,
Counter,
Histogram,
MeterProvider,
ObservableCounter,
ObservableGauge,
ObservableUpDownCounter,
UpDownCounter,
)
from opentelemetry.sdk.metrics.export import (
AggregationTemporality,
PeriodicExportingMetricReader,
)
from opentelemetry.sdk.metrics.view import (
ExplicitBucketHistogramAggregation,
View,
)
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import SpanLimits, TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.sampling import ALWAYS_ON, ParentBased
from src.config.settings import Telemetry as TelemetrySettings
from src.utils.constants import (
HTTP_DURATION_BUCKETS,
JOB_DURATION_BUCKETS,
METRIC_HTTP_SERVER_DURATION,
METRIC_JOB_DURATION,
METRIC_JOB_TIME_TO_READY,
TELEMETRY_LOG_ATTRIBUTE_LENGTH,
TELEMETRY_LOGS_PATH,
TELEMETRY_MAX_ATTRIBUTES,
TELEMETRY_METRICS_PATH,
TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
TELEMETRY_TRACES_PATH,
TIME_TO_READY_BUCKETS,
)
# все инструменты — cumulative: Prometheus забирает накопленное (решение 3)
_CUMULATIVE = dict.fromkeys(
(
Counter,
UpDownCounter,
Histogram,
ObservableCounter,
ObservableUpDownCounter,
ObservableGauge,
),
AggregationTemporality.CUMULATIVE,
)
# границы buckets histogram по имени инструмента
_BUCKETS = {
METRIC_HTTP_SERVER_DURATION: HTTP_DURATION_BUCKETS,
METRIC_JOB_DURATION: JOB_DURATION_BUCKETS,
METRIC_JOB_TIME_TO_READY: TIME_TO_READY_BUCKETS,
}
@dataclass(frozen=True, slots=True)
class Providers:
tracer_provider: TracerProvider
meter_provider: MeterProvider
logger_provider: LoggerProvider
def build(
*,
resource: Mapping[str, Any],
config: TelemetrySettings,
exporters: Any | None,
) -> Providers:
"""Провайдеры трасс, метрик и логов. `exporters` — получатели вместо OTLP
(`core.Exporters`, быстрые тесты) или `None`."""
if exporters is None:
exporters = otlp_exporters(config)
attributes = Resource(dict(resource))
timeout_ms = config.export_timeout_seconds * 1000
delay_ms = config.schedule_delay_seconds * 1000
tracer_provider = TracerProvider(
sampler=ParentBased(ALWAYS_ON),
resource=attributes,
shutdown_on_exit=False,
span_limits=SpanLimits(
max_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_events=TELEMETRY_MAX_ATTRIBUTES,
max_links=TELEMETRY_MAX_ATTRIBUTES,
max_span_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_event_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_link_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
max_span_attribute_length=TELEMETRY_SPAN_ATTRIBUTE_LENGTH,
),
)
tracer_provider.add_span_processor(
BatchSpanProcessor(
exporters.spans,
max_queue_size=config.max_queue_size,
schedule_delay_millis=delay_ms,
max_export_batch_size=config.max_export_batch_size,
export_timeout_millis=timeout_ms,
),
)
meter_provider = MeterProvider(
metric_readers=[exporters.metrics],
resource=attributes,
exemplar_filter=AlwaysOffExemplarFilter(),
shutdown_on_exit=False,
views=[
View(
instrument_name=name,
aggregation=ExplicitBucketHistogramAggregation(
boundaries=boundaries,
),
)
for name, boundaries in _BUCKETS.items()
],
)
logger_provider = LoggerProvider(
resource=attributes,
shutdown_on_exit=False,
log_record_limits=LogRecordLimits(
max_attributes=TELEMETRY_MAX_ATTRIBUTES,
max_attribute_length=TELEMETRY_LOG_ATTRIBUTE_LENGTH,
),
)
logger_provider.add_log_record_processor(
BatchLogRecordProcessor(
exporters.logs,
schedule_delay_millis=delay_ms,
max_export_batch_size=config.max_export_batch_size,
export_timeout_millis=timeout_ms,
max_queue_size=config.max_queue_size,
),
)
return Providers(
tracer_provider=tracer_provider,
meter_provider=meter_provider,
logger_provider=logger_provider,
)
def export_session() -> requests.Session:
"""Сессия отправки без окружения: `HTTP(S)_PROXY`, `NO_PROXY`, `.netrc`
и `REQUESTS_CA_BUNDLE` на неё не действуют — данные идут только по адресу
`[telemetry]` (verify S5 change `otel-telemetry`, как с `OTEL_*`)."""
session = requests.Session()
session.trust_env = False
return session
def otlp_exporters(config: TelemetrySettings) -> Any:
"""OTLP/HTTP protobuf только из `[telemetry]`: адрес, срок, без
заголовков и сжатия, своя сессия без прокси окружения."""
# тип получателей живёт в core: он нужен быстрым тестам без этого модуля
from src.infra.telemetry.core import Exporters
timeout = config.export_timeout_seconds
endpoint = config.otlp_endpoint
return Exporters(
spans=OTLPSpanExporter(
endpoint=endpoint + TELEMETRY_TRACES_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
session=export_session(),
),
metrics=PeriodicExportingMetricReader(
OTLPMetricExporter(
endpoint=endpoint + TELEMETRY_METRICS_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
preferred_temporality=_CUMULATIVE,
session=export_session(),
),
export_interval_millis=config.metric_export_interval_seconds
* 1000,
export_timeout_millis=timeout * 1000,
),
logs=OTLPLogExporter(
endpoint=endpoint + TELEMETRY_LOGS_PATH,
headers={},
timeout=timeout,
compression=Compression.NoCompression,
session=export_session(),
),
)
+23 -5
View File
@@ -1,10 +1,13 @@
"""Запуск телеметрии точкой входа процесса (API, worker)."""
"""Запуск телеметрии точкой входа процесса (API, worker, relay)."""
from pathlib import Path
from src.config import settings
from src.infra.logger import AbstractLogger, get_logger
from src.infra.telemetry import core
from src.infra.telemetry import container, core
from src.infra.telemetry.core import Exporters
from src.infra.telemetry.logs import install_log_hooks
from src.utils.constants import CGROUP_ROOT
logger: AbstractLogger = get_logger().bind(module="telemetry")
@@ -13,10 +16,13 @@ def start_process_telemetry(
service_name: str,
*,
exporters: Exporters | None = None,
cgroup_root: Path | str = CGROUP_ROOT,
) -> bool:
"""По `[telemetry]`: выключено — ничего. Включено — `OTEL_*` удаляются
из окружения с `warning` (имена без значений), затем провайдеры и хуки
журнала. `True` — телеметрия работает."""
"""По `[telemetry]`: выключено — ничего, модули SDK не загружаются.
Включено — `OTEL_*` удаляются из окружения с `warning` (имена без
значений), затем провайдеры, метрики контейнера по cgroup v2 (design
change `job-trace-propagation`, решение 12) и хуки журнала. `True` —
телеметрия работает."""
config = settings.telemetry
if not config.enabled and exporters is None:
return False
@@ -27,6 +33,18 @@ def start_process_telemetry(
config=config,
exporters=exporters,
)
meter = core.meter()
root = Path(cgroup_root)
if meter is not None:
if container.available(root):
container.register(meter, root=root)
else:
# до хуков журнала: одна запись в stdout, на хосте без cgroup
# (macOS) журнал в хранилище логов не меняется
logger.warning(
"Container metrics are unavailable",
cgroup_root=str(root),
)
install_log_hooks()
if ignored:
logger.warning(
+88 -3
View File
@@ -11,6 +11,12 @@ SIGTERM: текущий шаг доводится до фиксации или
сигнал прерывает сразу, «Stopped relay», код 0. Незаписанная отметка ничего не
теряет: следующий запуск опубликует задание снова.
Телеметрия (design change `job-trace-propagation`, решения 3, 7, 9): SDK по
`[telemetry]`, span producer — только публикации заданий с сохранённым
контекстом, проходы и их обращения к PostgreSQL трасс не начинают; снимок
очереди — после успешного прохода не чаще 5 с; закрытие SDK — в окне закрытия
клиентов 0,5 с. Команда replay SDK не запускает.
`python -m src.relay replay [--attachment-id ID]... [--error-code C] [--reason R]
[--limit N] [--apply] [--operator NAME]` — операторская команда реестра `failed`, по
умолчанию показ. Нужен только PostgreSQL. Коды: 0 — выбранное показано или
@@ -21,6 +27,7 @@ SIGTERM: текущий шаг доводится до фиксации или
import argparse
import asyncio
import signal
import time
from contextlib import suppress
from uuid import UUID
@@ -28,12 +35,17 @@ from src.config import settings
from src.core import exceptions
from src.core.services.attachment_relay import AttachmentRelayService
from src.core.services.attachment_replay import AttachmentReplayService
from src.infra import early_stop
from src.infra import early_stop, telemetry
from src.infra.broker import JobPublisher
from src.infra.db import create_engine, create_session_factory
from src.infra.db.uow import SqlAlchemyUnitOfWork
from src.infra.logger import AbstractLogger, get_logger
from src.schemas import dataclasses
from src.schemas.enums import AttachmentErrorCode, AttachmentJobReason
from src.utils.constants import (
QUEUE_SNAPSHOT_INTERVAL_SECONDS,
TELEMETRY_SERVICE_RELAY,
)
logger: AbstractLogger = get_logger().bind(module="relay")
@@ -140,11 +152,39 @@ def _install_stop() -> asyncio.Event:
return stop
class QueueSnapshots:
"""Последний снимок очереди процесса relay: его читают gauge глубины и
возраста (design change `job-trace-propagation`, решение 9)."""
def __init__(self) -> None:
self.latest: dataclasses.QueueSnapshotDTO | None = None
self._taken_at: float | None = None
def due(self, now: float) -> bool:
return (
self._taken_at is None
or now - self._taken_at >= QUEUE_SNAPSHOT_INTERVAL_SECONDS
)
def store(
self,
snapshot: dataclasses.QueueSnapshotDTO,
*,
now: float,
) -> None:
self.latest = snapshot
self._taken_at = now
async def run() -> int:
stop = _install_stop()
relay = settings.relay
namespace = settings.database.name
telemetry_enabled = telemetry.start_process_telemetry(
TELEMETRY_SERVICE_RELAY,
)
engine = create_engine(settings.database)
telemetry.instrument_engine(engine)
session_factory = create_session_factory(engine)
publisher = JobPublisher(settings.broker, namespace=namespace)
service = AttachmentRelayService(
@@ -154,6 +194,12 @@ async def run() -> int:
),
publisher=publisher,
)
snapshots = QueueSnapshots() if telemetry_enabled else None
if snapshots is not None:
telemetry.observe_queue(
queue=publisher.queue,
latest=lambda: snapshots.latest,
)
try:
logger.info(
"Started relay",
@@ -172,27 +218,64 @@ async def run() -> int:
database_port=settings.database.port,
database_name=namespace,
database_pool_size=settings.database.pool_size,
telemetry_enabled=telemetry_enabled,
telemetry_endpoint=(
settings.telemetry.otlp_endpoint if telemetry_enabled else None
),
telemetry_environment=(
settings.telemetry.environment if telemetry_enabled else None
),
)
await _serve(service, stop=stop)
await _serve(service, stop=stop, snapshots=snapshots)
finally:
# закрытие SDK — в том же окне, что клиенты (как у worker): потоки
# стартуют до gather, что не ушло за срок — теряется
closing = telemetry.begin_shutdown()
with suppress(Exception):
async with asyncio.timeout(_CLOSE_TIMEOUT_SECONDS):
await asyncio.gather(
engine.dispose(),
publisher.aclose(),
telemetry.wait_closed(
closing,
timeout=_CLOSE_TIMEOUT_SECONDS,
),
return_exceptions=True,
)
# после закрытия SDK — только stdout
logger.info("Stopped relay", exit_code=EXIT_OK)
return EXIT_OK
async def _take_snapshot(
service: AttachmentRelayService,
snapshots: QueueSnapshots | None,
) -> None:
"""Снимок очереди не чаще `QUEUE_SNAPSHOT_INTERVAL_SECONDS`, только при
включённой телеметрии; отказ PostgreSQL — пропуск: устаревший снимок
gauge перестаёт отдавать сам."""
if snapshots is None:
return
now = time.monotonic()
if not snapshots.due(now):
return
try:
snapshot = await service.queue_snapshot()
except exceptions.ServiceUnavailable:
# причину уже записала единица работы
return
snapshots.store(snapshot, now=now)
async def _serve(
service: AttachmentRelayService,
*,
stop: asyncio.Event,
snapshots: QueueSnapshots | None = None,
) -> None:
"""Проходы до сигнала. Пакет полон — следующий проход сразу, отказ — пауза
отказа, иначе — пауза опроса."""
отказа, иначе — пауза опроса. После успешного прохода — снимок очереди
(решение 9)."""
relay = settings.relay
while not stop.is_set():
try:
@@ -210,6 +293,8 @@ async def _serve(
logger.error("Relay pass failed", exc_info=e)
pause = relay.failure_pause_seconds
else:
if not stop.is_set():
await _take_snapshot(service, snapshots)
if result.unconfirmed:
pause = relay.failure_pause_seconds
elif result.selected >= relay.batch_size:
+8
View File
@@ -7,6 +7,9 @@ from .attachment import (
AttachmentVariantDTO,
CleanupPassDTO,
FailedJobDTO,
JobDeliveryResultDTO,
JobPublicationDTO,
QueueSnapshotDTO,
ReconcileFindingDTO,
ReconcilePassDTO,
RelayPassDTO,
@@ -15,6 +18,7 @@ from .attachment import (
ReplayPassDTO,
ReplayResultDTO,
StagingCleanupPassDTO,
TraceContextDTO,
)
from .chat import ChatFullDTO, ChatPageDTO
from .idempotency import IdempotencyRecordDTO
@@ -35,8 +39,11 @@ __all__ = [
"CurrentSessionDTO",
"FailedJobDTO",
"IdempotencyRecordDTO",
"JobDeliveryResultDTO",
"JobPublicationDTO",
"MessageFullDTO",
"MessagePageDTO",
"QueueSnapshotDTO",
"ReconcileFindingDTO",
"ReconcilePassDTO",
"RelayPassDTO",
@@ -47,6 +54,7 @@ __all__ = [
"SessionFullDTO",
"SessionTokenDTO",
"StagingCleanupPassDTO",
"TraceContextDTO",
"UserCredentialsDTO",
"UserFullDTO",
]
+60
View File
@@ -6,10 +6,12 @@ from uuid import UUID
from src.schemas.enums import (
AttachmentErrorCode,
AttachmentJobReason,
AttachmentJobState,
AttachmentStatus,
AttachmentVariantName,
ImageType,
JobDeliveryOutcome,
ReconcileFinding,
ReconcileStrategy,
)
@@ -123,6 +125,64 @@ class AttachmentJobDTO:
published_at: datetime | None = None
finished_at: datetime | None = None
attempt_base: int = 0
# контекст W3C server span загрузки (design change
# `job-trace-propagation`, решение 4); NULL — строка прежней версии или
# реплика без телеметрии
traceparent: str | None = None
tracestate: str | None = None
@dataclass(frozen=True, slots=True)
class TraceContextDTO:
"""Контекст W3C Trace Context: значение заголовков `traceparent` и
`tracestate` (design change `job-trace-propagation`, решения 1, 4).
Только идентификаторы трассы и span и флаги, без baggage."""
traceparent: str
tracestate: str | None = None
@dataclass(frozen=True, slots=True)
class JobPublicationDTO:
"""Элемент публикации relay (решение 3): `attempt` — номер попытки в
сообщении, `replayed` — задание возвращено replay, `retry_reason` —
причина повтора (прежний `last_error_code`), `trace_context` — контекст
задания или `None`."""
job_id: UUID
body: bytes
attempt: int
replayed: bool = False
retry_reason: str | None = None
trace_context: TraceContextDTO | None = None
@dataclass(frozen=True, slots=True)
class JobDeliveryResultDTO:
"""Итог доставки worker (решение 8): исход, взятая попытка (у `dropped`
— нет), причина у `retry` и `failed`, код ошибки у `failed`, время до
готовности — только у `ready` без replay."""
outcome: JobDeliveryOutcome
attempt: int | None = None
reason: AttachmentJobReason | None = None
error_code: AttachmentErrorCode | None = None
time_to_ready_seconds: float | None = None
@dataclass(frozen=True, slots=True)
class QueueSnapshotDTO:
"""Снимок незавершённых заданий по стадиям (решение 9): время снимка,
`scheduled` — ждут срока, `outbox` — срок наступил, не опубликованы,
`published` — опубликованы, не взяты, `processing` — идёт попытка;
`oldest_created_at` — приём старейшего незавершённого или `None`."""
taken_at: datetime
scheduled: int
outbox: int
published: int
processing: int
oldest_created_at: datetime | None = None
@dataclass(frozen=True, slots=True)
+8 -7
View File
@@ -16,18 +16,19 @@ from src.schemas.dataclasses import AttachmentJobDTO
from src.utils.constants import (
ATTACHMENT_JOB_SCHEMA_VERSION,
ATTACHMENT_JOB_TYPE,
TRACEPARENT_PATTERN,
TRACESTATE_MAX_LENGTH,
)
from src.utils.utc import to_rfc3339
_TRACEPARENT_PATTERN = r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"
_TRACESTATE_MAX_LENGTH = 512
class AttachmentJobMessage(BaseModel):
"""Тело сообщения; лишнее поле и чужая версия — ошибка разбора.
`traceparent` и `tracestate` на этом уровне приложение не пишет и не
читает, но принимает: их допускает контракт.
`traceparent` и `tracestate` в теле приложение не пишет и не читает, но
принимает: их допускает контракт. Контекст едет в заголовках сообщения
AMQP с тем же значением W3C (design change `job-trace-propagation`,
решение 1).
"""
model_config = ConfigDict(extra="forbid")
@@ -39,11 +40,11 @@ class AttachmentJobMessage(BaseModel):
pipeline_version: Annotated[int, Field(ge=1, strict=True)]
attempt: Annotated[int, Field(ge=1, strict=True)]
created_at: datetime
traceparent: Annotated[str, Field(pattern=_TRACEPARENT_PATTERN)] | None = (
traceparent: Annotated[str, Field(pattern=TRACEPARENT_PATTERN)] | None = (
None
)
tracestate: (
Annotated[str, Field(max_length=_TRACESTATE_MAX_LENGTH)] | None
Annotated[str, Field(max_length=TRACESTATE_MAX_LENGTH)] | None
) = None
+62
View File
@@ -132,6 +132,10 @@ PAGE_LIMIT_DEFAULT = 50
DB_APPLICATION_NAME = "mtusi-messenger"
# секунды на проверку Postgres в /health/ready
READINESS_DB_TIMEOUT_SECONDS = 2
# логгер пула engine: SQLAlchemy называет его модулем и классом пула
# (`CountingQueuePool`, design change `job-trace-propagation`, решение 10);
# журнал держит его на WARNING, как прежний пул SQLAlchemy
DB_POOL_LOGGER = "src.infra.db.engine.CountingQueuePool"
# секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой
# срок; дальше соединение обрывается
DB_CLOSE_TIMEOUT_SECONDS = 2
@@ -224,6 +228,64 @@ ATTR_RENDER_OUTCOME = "messenger.render.outcome"
ATTR_RENDER_EXIT_CODE = "messenger.render.exit_code"
ATTR_RENDER_PEAK_KIB = "messenger.render.peak_kib"
# сквозная трасса и сигналы уровня 4 (design change `job-trace-propagation`,
# решения 1–13)
TELEMETRY_SERVICE_RELAY = "messenger-relay"
# W3C Trace Context: версия 00, как шаблон contracts/jobs.schema.json; те же
# значения — колонки attachment_jobs и заголовки сообщения AMQP
TRACEPARENT_PATTERN = r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"
TRACESTATE_MAX_LENGTH = 512
TRACE_HEADER_TRACEPARENT = "traceparent"
TRACE_HEADER_TRACESTATE = "tracestate"
# span брокера (semantic conventions messaging)
MESSAGING_SYSTEM = "rabbitmq"
MESSAGING_OPERATION_PUBLISH = "publish"
MESSAGING_OPERATION_PROCESS = "process"
ATTR_MESSAGING_SYSTEM = "messaging.system"
ATTR_MESSAGING_DESTINATION = "messaging.destination.name"
ATTR_MESSAGING_OPERATION_TYPE = "messaging.operation.type"
ATTR_MESSAGING_OPERATION_NAME = "messaging.operation.name"
ATTR_JOB_ATTEMPT = "messenger.job.attempt"
ATTR_JOB_REPLAYED = "messenger.job.replayed"
ATTR_JOB_RETRY_REASON = "messenger.job.retry_reason"
ATTR_JOB_REDELIVERED = "messenger.job.redelivered"
ATTR_JOB_REASON = "messenger.job.reason"
ATTR_JOB_ERROR_CODE = "messenger.job.error_code"
# метрики уровня 4 (таблица решения 13)
METRIC_JOB_TIME_TO_READY = "messenger.job.time_to_ready"
METRIC_QUEUE_DEPTH = "messenger.queue.depth"
METRIC_QUEUE_OLDEST_AGE = "messenger.queue.oldest_age"
METRIC_DB_CONNECTION_COUNT = "db.client.connection.count"
METRIC_DB_CONNECTION_MAX = "db.client.connection.max"
METRIC_DB_CONNECTION_PENDING = "db.client.connection.pending_requests"
METRIC_DB_CONNECTION_TIMEOUTS = "db.client.connection.timeouts"
METRIC_WORKER_BUSY = "messenger.worker.busy"
METRIC_WORKER_CAPACITY = "messenger.worker.capacity"
METRIC_WORKER_WAITING = "messenger.worker.waiting"
METRIC_CONTAINER_CPU_TIME = "container.cpu.time"
METRIC_CONTAINER_MEMORY_USAGE = "container.memory.usage"
METRIC_CONTAINER_CPU_LIMIT = "messenger.container.cpu.limit"
METRIC_CONTAINER_MEMORY_LIMIT = "messenger.container.memory.limit"
ATTR_QUEUE_STAGE = "messenger.queue.stage"
ATTR_DB_POOL_NAME = "db.client.connection.pool.name"
ATTR_DB_CONNECTION_STATE = "db.client.connection.state"
DB_CONNECTION_STATE_USED = "used"
DB_CONNECTION_STATE_IDLE = "idle"
# стадии незавершённых заданий: ждёт срока следующей попытки, срок наступил и
# не опубликовано, опубликовано и не взято, идёт попытка
QUEUE_STAGE_SCHEDULED = "scheduled"
QUEUE_STAGE_OUTBOX = "outbox"
QUEUE_STAGE_PUBLISHED = "published"
QUEUE_STAGE_PROCESSING = "processing"
# время до ready, секунды: путь без повторов 0,5–2 с, бюджет smoke 60 с,
# паузы повторов до 75 с, возврат по аренде 70 с, наибольшая пауза 300 с
TIME_TO_READY_BUCKETS = (0.25, 0.5, 1, 2.5, 5, 10, 20, 30, 60, 120, 300, 600)
# снимок очереди relay: не чаще раза в интервал; старше срока не отдаётся
QUEUE_SNAPSHOT_INTERVAL_SECONDS = 5
QUEUE_SNAPSHOT_STALE_SECONDS = 30
# cgroup v2 контейнера изнутри (решение 12)
CGROUP_ROOT = "/sys/fs/cgroup"
# хранилище объектов (S3)
# имя bucket по правилам S3: 3–63 символа, строчные латинские буквы,
# цифры, точка и дефис, по краям — буква или цифра
+72 -36
View File
@@ -42,6 +42,7 @@ from src.infra.db.uow import SqlAlchemyUnitOfWork
from src.infra.logger import AbstractLogger, get_logger
from src.infra.render import ImageRenderer
from src.infra.s3 import ObjectStorage, create_object_storage
from src.schemas.dataclasses import JobDeliveryResultDTO
from src.schemas.enums import JobDeliveryOutcome, JobOutcome
from src.utils.constants import ATTACHMENT_JOB_TYPE, TELEMETRY_SERVICE_WORKER
@@ -106,6 +107,9 @@ async def run() -> int:
stop=stop,
)
load = telemetry.WorkerLoad()
telemetry.observe_worker(capacity=worker.concurrency, load=load)
try:
if not (
settings.s3.access_key_id.get_secret_value()
@@ -146,7 +150,7 @@ async def run() -> int:
settings.telemetry.environment if telemetry_enabled else None
),
)
await _serve(make_service, namespace=namespace, stop=stop)
await _serve(make_service, namespace=namespace, stop=stop, load=load)
finally:
# одним сроком, а не по очереди: сумма не растёт с числом клиентов
# (S5). Закрытие SDK — в том же окне: потоки стартуют до gather и
@@ -173,6 +177,7 @@ async def _serve(
*,
namespace: str,
stop: asyncio.Event,
load: telemetry.WorkerLoad,
) -> None:
"""Соединения с брокером до сигнала."""
worker = settings.worker
@@ -197,7 +202,7 @@ async def _serve(
continue
logger.info("Connected to broker", broker_queue=consumer.queue)
pump = asyncio.create_task(
_pump(consumer, make_service, slots, tasks, stop),
_pump(consumer, make_service, slots, tasks, stop, load),
)
stopping = asyncio.create_task(stop.wait())
await asyncio.wait(
@@ -236,12 +241,13 @@ async def _pump(
slots: asyncio.Semaphore,
tasks: set[asyncio.Task[None]],
stop: asyncio.Event,
load: telemetry.WorkerLoad,
) -> None:
"""Каждая доставка — своя задача со своим контекстом журнала и своим
сервисом."""
async for delivery in consumer.deliveries():
task = asyncio.create_task(
_handle(make_service, delivery, slots, stop),
_handle(make_service, delivery, slots, stop, load=load),
)
tasks.add(task)
task.add_done_callback(tasks.discard)
@@ -252,45 +258,75 @@ async def _handle(
delivery: JobDelivery,
slots: asyncio.Semaphore,
stop: asyncio.Event,
*,
load: telemetry.WorkerLoad | None = None,
) -> None:
"""Подтверждение — только после итога сервиса. Отмена при остановке
сообщение не подтверждает: брокер вернёт его после закрытия соединения.
Сообщение сверх конкуренции ждёт место без взятия; после сигнала остановки
попытка не начинается."""
async with slots:
if stop.is_set():
return
# span и наблюдение histogram — после места конкуренции: ожидание
# места — не работа (design change otel-telemetry, решение 11);
# подтверждение — внутри span
with telemetry.consumer_span(
queue=queue_name(settings.database.name),
job_type=ATTACHMENT_JOB_TYPE,
) as observation:
started = time.monotonic()
попытка не начинается. `load` — счётчики «ждут места» и «заняты» для
метрик насыщения (design change `job-trace-propagation`, решение 11),
снимаются в `finally`."""
if load is None:
load = telemetry.WorkerLoad()
load.waiting += 1
waiting = True
try:
async with slots:
load.waiting -= 1
waiting = False
load.busy += 1
try:
outcome = await make_service().handle(
body=delivery.body,
redelivered=delivery.redelivered,
)
except Exception as e:
observation.finish(
outcome=JobDeliveryOutcome.ERROR.value,
duration_seconds=time.monotonic() - started,
error=e,
)
logger.error("Job handling failed", exc_info=e)
with suppress(TimeoutError):
await asyncio.wait_for(
stop.wait(),
timeout=settings.worker.reconnect_seconds,
)
outcome = JobDeliveryOutcome.ERROR
observation.finish(
outcome=outcome.value,
duration_seconds=time.monotonic() - started,
if stop.is_set():
return
await _process(make_service, delivery, stop)
finally:
load.busy -= 1
finally:
if waiting:
load.waiting -= 1
async def _process(
make_service: Callable[[], AttachmentProcessingService],
delivery: JobDelivery,
stop: asyncio.Event,
) -> None:
"""Доставка на месте конкуренции. Span и наблюдение histogram — после
места: ожидание места — не работа (design change otel-telemetry, решение
11); подтверждение — внутри span. Span — дочерний к контексту из заголовков
сообщения, с link на него; без контекста — корень (design change
job-trace-propagation, решение 2)."""
with telemetry.consumer_span(
queue=queue_name(settings.database.name),
job_type=ATTACHMENT_JOB_TYPE,
parent=delivery.trace_context,
redelivered=delivery.redelivered,
) as observation:
started = time.monotonic()
try:
result = await make_service().handle(
body=delivery.body,
redelivered=delivery.redelivered,
)
await _settle(delivery, outcome.action)
except Exception as e:
result = JobDeliveryResultDTO(outcome=JobDeliveryOutcome.ERROR)
observation.finish(
result=result,
duration_seconds=time.monotonic() - started,
error=e,
)
logger.error("Job handling failed", exc_info=e)
with suppress(TimeoutError):
await asyncio.wait_for(
stop.wait(),
timeout=settings.worker.reconnect_seconds,
)
observation.finish(
result=result,
duration_seconds=time.monotonic() - started,
)
await _settle(delivery, result.outcome.action)
async def _settle(delivery: JobDelivery, action: JobOutcome) -> None: