Поля LogRecord

Внутреннее представление строки лога. Каждый биндинг отдаёт типизированный dataclass LogRecord с полями ниже; wire-сериализация живёт в отдельных функциях (см. Форматы передачи).

Таблица полей

Поле	Тип	Опционально	По умолчанию	Заполняется	Значение
time_unix_nano	int (uint64)	нет	time.time_ns() на emit	producer	Timestamp emit, наносекунды от Unix epoch (OTel TimeUnixNano).
severity_number	int	нет	—	вызывающий	OTel severity 1-24.
severity_text	str	нет	производное от severity_number	биндинг	Одна из шести канонических строк (TRACE, DEBUG, INFO, WARN, ERROR, FATAL).
body	Value	нет	—	вызывающий	Основное сообщение — строка или структура (map/array/scalar).
attributes	dict[str, Value]	да	{}	вызывающий + биндинг	Per-record key-value контекст. Маскирование применяется до fan-out.
instrumentation_scope	InstrumentationScope?	да	null	биндинг	Self-descriptor логгера (имя, версия). Заполняется, когда используется Logger.get(name, version).
resource	Resource?	да	null	биндинг	Атрибуты процесса/сервиса/хоста. Унаследованы от root-логгера после configure(resource_attributes=...).
trace_id	bytes(16)?	да	null	биндинг	W3C Trace Context — 16 случайных байт. Заполняется из OTel-контекста, если активен span.
span_id	bytes(8)?	да	null	биндинг	W3C Trace Context — 8 случайных байт. Тот же источник, что у trace_id.
trace_flags	int (uint8)	нет	0	биндинг	Флаги W3C (бит sampled и т.п.). 0 = не сэмплировано.
observed_time_unix_nano	int? (uint64)	да	null	приёмник (на ingest)	Timestamp ingest на приёмнике. Producer оставляет null; приёмник заполняет до wire-сериализации (по спеке §1).

Тип Value

Value — это рекурсивный sum-тип, используемый для body и значений атрибутов. Конкретная форма:

Value = str | int | float | bool | null | dict[str, Value] | list[Value]

Та же форма стоит за ConfigTree в config-spec §1; потребители могут переиспользовать один language-level тип, чтобы представлять и то и другое. Значения JSON-сериализуемы (множество Value ровно совпадает с множеством JSON-значений).

InstrumentationScope

Self-descriptor логгера, отправившего запись:

Поле	Тип	Значение
name	str	Имя логгера (совпадает с аргументом Logger.get(name)).
version	str?	Семантическая версия, задаётся через Logger.get(name, version).
attributes	dict[str, Value]	Опциональные атрибуты scope-уровня.

Для записей, отправленных плагином, scope рекомендуется выставлять равным id и version плагина из его PluginManifest (см. dagstack/plugin-system-spec).

Resource

Атрибуты уровня процесса, общие для всех логгеров в процессе:

Поле	Тип	Значение
attributes	dict[str, Value]	OTel Resource-атрибуты — service.name, service.version, service.instance.id, deployment.environment, host.name, process.pid, telemetry.sdk.{name,version,language} и т.п.

Биндинг определяет Resource-атрибуты через:

1. Autodetect OTel (env-переменная OTEL_RESOURCE_ATTRIBUTES, OTel Resource Detectors).
2. Явный конфиг из секции logging.resource.*.
3. Слияние: env-detected ∪ config-supplied (config выигрывает).

Владение полями

По спеке §1 правила владения:

• Вызывающий задаёт severity_number, body, опциональные attributes. Вызывающий никогда не выставляет time_unix_nano напрямую; биндинг заполняет его на emit.
• Биндинг заполняет time_unix_nano, severity_text, instrumentation_scope, resource, trace_id, span_id, trace_flags плюс любые атрибуты, добавленные через проброс Baggage.
• Приёмник заполняет observed_time_unix_nano, если producer оставил его null. Это гарантирует, что wire-вывод всегда несёт ingest-timestamp.

Обзор кодирования на wire

Тот же набор полей сериализуется в три формата с правилами кодирования, специфичными для каждого формата. Полную таблицу смотри в Формате передачи; короткая версия:

Поле	OTLP protobuf	OTel JSON	dagstack JSON-lines
time_unix_nano	fixed64	строка-десятичная	int (Canonical JSON допускает int64)
trace_id	bytes(16)	lowercase 32-hex	lowercase 32-hex
span_id	bytes(8)	lowercase 16-hex	lowercase 16-hex
severity_number	int	int	int
severity_text	string	string	string
Регистр	(бинарный)	camelCase	snake_case

См. также

• Справочная таблица уровней — полное перечисление 24 строк.
• Форматы передачи — правила кодирования на формат.
• Проброс контекста — что заполняет trace_id / span_id.
• ADR-0001 §1 (полный нормативный текст).