telemetry-dev 0.1.0__py3-none-any.whl

telemetry_dev/__init__.py

@@ -0,0 +1,55 @@
+"""telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics.
+
+Quickstart::
+
+    import telemetry_dev
+
+    telemetry_dev.init()  # reads TELEMETRY_DEV_API_KEY
+
+    with telemetry_dev.start_span("chat gpt-4o", type="generation", model="gpt-4o",
+                                  provider="openai", input=messages) as span:
+        ...
+        span.update(output=completion, usage={"input_tokens": 11, "output_tokens": 7})
+"""
+
+from ._client import Client, flush, get_client, init, shutdown
+from ._config import SDK_VERSION as __version__
+from ._config import LogLevelOption
+from ._context import get_traceparent, propagate_attributes
+from ._logs import log
+from ._observe import observe
+from ._semconv import LogLevel, SpanType
+from ._serialize import AttributeValue, Mask, MaskContext
+from ._spans import (
+    NOT_GIVEN,
+    SpanHandle,
+    Usage,
+    start_span,
+    update_current_span,
+)
+from .otel import TelemetrySpanProcessor
+
+__all__ = [
+    "NOT_GIVEN",
+    "AttributeValue",
+    "Client",
+    "LogLevel",
+    "LogLevelOption",
+    "Mask",
+    "MaskContext",
+    "SpanHandle",
+    "SpanType",
+    "TelemetrySpanProcessor",
+    "Usage",
+    "__version__",
+    "flush",
+    "get_client",
+    "get_traceparent",
+    "init",
+    "log",
+    "observe",
+    "propagate_attributes",
+    "shutdown",
+    "start_span",
+    "update_current_span",
+]

telemetry_dev/_client.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import atexit
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry._logs import Logger as OtelLogger
+from opentelemetry.exporter.otlp.proto.http import Compression
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import (
+    BatchLogRecordProcessor,
+    LogRecordExporter,
+    LogRecordExportResult,
+    SimpleLogRecordProcessor,
+)
+from opentelemetry.sdk.metrics import Histogram, MeterProvider
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    MetricReader,
+    PeriodicExportingMetricReader,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import ReadableSpan, SpanLimits, TracerProvider
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.trace import Tracer
+
+from ._config import (
+    SDK_VERSION,
+    LogLevelOption,
+    ResolvedConfig,
+    configure_logger,
+    logger,
+    report_error,
+    resolve_config,
+)
+from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder
+from ._processor import ExportMode, StampingSpanProcessor
+from ._semconv import SCOPE_NAME
+from ._serialize import Mask, serialize_content
+
+_lock = threading.RLock()
+_client: Client | None = None
+
+
+def _default_scope_filter(span: ReadableSpan) -> bool:
+    scope = span.instrumentation_scope
+    return scope is not None and scope.name == SCOPE_NAME
+
+
+class _ReportingSpanExporter(SpanExporter):
+    """Surfaces transport failures to on_error (TS parity: exporters route errors to onError,
+    the stock OTLP exporter only logs them)."""
+
+    def __init__(
+        self, inner: SpanExporter, on_error: Callable[[BaseException], None] | None
+    ) -> None:
+        self._inner = inner
+        self._on_error = on_error
+
+    def export(self, spans: Any) -> SpanExportResult:
+        try:
+            result = self._inner.export(spans)
+        except BaseException as exc:
+            report_error(self._on_error, "span export failed", exc)
+            return SpanExportResult.FAILURE
+        if result is SpanExportResult.FAILURE:
+            report_error(
+                self._on_error,
+                "span export failed",
+                RuntimeError("OTLP span export failed (check the API key and ingest URL)"),
+            )
+        return result
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._inner.force_flush(timeout_millis)
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()
+
+
+class _ReportingLogExporter(LogRecordExporter):
+    """Log-exporter twin of _ReportingSpanExporter."""
+
+    def __init__(
+        self, inner: LogRecordExporter, on_error: Callable[[BaseException], None] | None
+    ) -> None:
+        self._inner = inner
+        self._on_error = on_error
+
+    def export(self, batch: Any) -> LogRecordExportResult:
+        try:
+            result = self._inner.export(batch)
+        except BaseException as exc:
+            report_error(self._on_error, "log export failed", exc)
+            return LogRecordExportResult.FAILURE
+        if result is LogRecordExportResult.FAILURE:
+            report_error(
+                self._on_error,
+                "log export failed",
+                RuntimeError("OTLP log export failed (check the API key and ingest URL)"),
+            )
+        return result
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        inner_flush = getattr(self._inner, "force_flush", None)
+        return inner_flush(timeout_millis) if inner_flush is not None else True
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()
+
+
+class Client:
+    """Holds the telemetry pipelines for one init() call. Obtain via telemetry_dev.init()."""
+
+    def __init__(
+        self,
+        *,
+        config: ResolvedConfig,
+        enabled: bool,
+        register_global: bool = False,
+        export_mode: ExportMode = "batched",
+        capture_input: bool = True,
+        capture_output: bool = True,
+        mask: Mask | None = None,
+        max_attribute_length: int = 65536,
+        span_filter: Callable[[ReadableSpan], bool] | None = None,
+        on_error: Callable[[BaseException], None] | None = None,
+        disable_atexit: bool = False,
+        timeout: float = 10.0,
+        span_exporter: SpanExporter | None = None,
+        log_exporter: LogRecordExporter | None = None,
+        metric_reader: MetricReader | None = None,
+    ) -> None:
+        self.enabled = enabled
+        self.config = config
+        self.capture_input = capture_input
+        self.capture_output = capture_output
+        self.mask = mask
+        self.max_attribute_length = max_attribute_length
+        self.on_error = on_error
+        self._shutdown = False
+        self._atexit_registered = False
+
+        self.processor: StampingSpanProcessor | None = None
+        self.tracer: Tracer | None = None
+        self.otel_logger: OtelLogger | None = None
+        self._tracer_provider: TracerProvider | None = None
+        self._logger_provider: LoggerProvider | None = None
+        self._meter_provider: MeterProvider | None = None
+
+        if not enabled:
+            return
+
+        headers = {"Authorization": f"Bearer {config.api_key}"}
+        resource = Resource.create(
+            {
+                "service.name": config.service_name,
+                "deployment.environment.name": config.environment,
+            }
+        )
+
+        # The funnel keeps capped content (marker included) within max_attribute_length, so
+        # the backstop can use the same cap for raw attributes set outside the funnel.
+        self._tracer_provider = TracerProvider(
+            resource=resource,
+            shutdown_on_exit=False,
+            span_limits=SpanLimits(
+                max_attribute_length=max_attribute_length,
+                max_span_attribute_length=max_attribute_length,
+            ),
+        )
+
+        # Without an api key (enabled via a test seam), never construct real network
+        # exporters — they would POST to the ingest with a bogus Authorization header.
+        if metric_reader is None and config.api_key is not None:
+            metric_exporter = GuardedOTLPMetricExporter(
+                endpoint=f"{config.base_url}/v1/metrics",
+                headers=headers,
+                compression=Compression.Gzip,
+                timeout=timeout,
+                preferred_temporality={Histogram: AggregationTemporality.DELTA},
+                on_error=on_error,
+            )
+            metric_reader = PeriodicExportingMetricReader(
+                metric_exporter, export_interval_millis=60_000
+            )
+        metrics_recorder: MetricsRecorder | None = None
+        if metric_reader is not None:
+            self._meter_provider = MeterProvider(
+                metric_readers=[metric_reader], resource=resource, shutdown_on_exit=False
+            )
+            meter = self._meter_provider.get_meter(SCOPE_NAME, SDK_VERSION)
+            metrics_recorder = MetricsRecorder(meter, on_error=on_error)
+
+        if span_exporter is None:
+            span_exporter = _ReportingSpanExporter(
+                OTLPSpanExporter(
+                    endpoint=f"{config.base_url}/v1/traces",
+                    headers=headers,
+                    compression=Compression.Gzip,
+                    timeout=timeout,
+                ),
+                on_error,
+            )
+        if span_filter is None and register_global:
+            span_filter = _default_scope_filter
+        self.processor = StampingSpanProcessor(
+            span_exporter,
+            export_mode=export_mode,
+            span_filter=span_filter,
+            metrics_recorder=metrics_recorder,
+            on_error=on_error,
+        )
+        self._tracer_provider.add_span_processor(self.processor)
+        self.tracer = self._tracer_provider.get_tracer(SCOPE_NAME, SDK_VERSION)
+
+        if log_exporter is None and config.api_key is not None:
+            log_exporter = _ReportingLogExporter(
+                OTLPLogExporter(
+                    endpoint=f"{config.base_url}/v1/logs",
+                    headers=headers,
+                    compression=Compression.Gzip,
+                    timeout=timeout,
+                ),
+                on_error,
+            )
+        if log_exporter is not None:
+            self._logger_provider = LoggerProvider(resource=resource, shutdown_on_exit=False)
+            if export_mode == "immediate":
+                self._logger_provider.add_log_record_processor(
+                    SimpleLogRecordProcessor(log_exporter)
+                )
+            else:
+                self._logger_provider.add_log_record_processor(
+                    BatchLogRecordProcessor(log_exporter)
+                )
+            self.otel_logger = self._logger_provider.get_logger(SCOPE_NAME, SDK_VERSION)
+
+        if register_global:
+            try:
+                trace.set_tracer_provider(self._tracer_provider)
+            except BaseException as exc:
+                self.report("failed to register global tracer provider", exc)
+
+        if not disable_atexit:
+            atexit.register(self.shutdown)
+            self._atexit_registered = True
+
+    def report(self, message: str, exc: BaseException) -> None:
+        report_error(self.on_error, message, exc)
+
+    def serialize(self, value: Any, key: str) -> str | None:
+        return serialize_content(
+            value,
+            key=key,
+            mask=self.mask,
+            max_len=self.max_attribute_length,
+            on_error=self.on_error,
+        )
+
+    def flush(self, timeout_s: float = 10.0) -> None:
+        if not self.enabled or self._shutdown:
+            return
+        timeout_millis = int(timeout_s * 1000)
+        try:
+            if self._tracer_provider is not None:
+                self._tracer_provider.force_flush(timeout_millis)
+            if self._logger_provider is not None:
+                self._logger_provider.force_flush(timeout_millis)
+            if self._meter_provider is not None:
+                self._meter_provider.force_flush(timeout_millis=timeout_millis)
+        except BaseException as exc:
+            self.report("flush failed", exc)
+
+    def shutdown(self, timeout_s: float = 10.0) -> None:
+        global _client
+        if self._shutdown:
+            return
+        self._shutdown = True
+        if self._atexit_registered:
+            try:
+                atexit.unregister(self.shutdown)
+            except BaseException:
+                pass
+        timeout_millis = int(timeout_s * 1000)
+        try:
+            if self._tracer_provider is not None:
+                self._tracer_provider.shutdown()
+            if self._logger_provider is not None:
+                self._logger_provider.shutdown()
+            if self._meter_provider is not None:
+                self._meter_provider.shutdown(timeout_millis=timeout_millis)
+        except BaseException as exc:
+            self.report("shutdown failed", exc)
+        with _lock:
+            if _client is self:
+                _client = None
+
+
+def init(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    environment: str | None = None,
+    service_name: str | None = None,
+    enabled: bool = True,
+    register_global: bool = False,
+    export_mode: ExportMode = "batched",
+    log_level: LogLevelOption = "warn",
+    capture_input: bool = True,
+    capture_output: bool = True,
+    mask: Mask | None = None,
+    max_attribute_length: int = 65536,
+    span_filter: Callable[[ReadableSpan], bool] | None = None,
+    on_error: Callable[[BaseException], None] | None = None,
+    disable_atexit: bool = False,
+    timeout: float = 10.0,
+    span_exporter: SpanExporter | None = None,
+    log_exporter: LogRecordExporter | None = None,
+    metric_reader: MetricReader | None = None,
+) -> Client:
+    """Initialize the telemetry.dev SDK. Fail-open: a missing API key yields a silent no-op
+    client; internal errors are routed to on_error and the 'telemetry_dev' logger, never raised."""
+    global _client
+    configure_logger(log_level)
+    config = resolve_config(
+        api_key=api_key,
+        base_url=base_url,
+        environment=environment,
+        service_name=service_name,
+    )
+    has_seam = span_exporter is not None or log_exporter is not None or metric_reader is not None
+    effective_enabled = enabled and (has_seam or config.api_key is not None)
+    if enabled and not effective_enabled:
+        logger.debug("telemetry-dev disabled: no API key")
+
+    try:
+        client = Client(
+            config=config,
+            enabled=effective_enabled,
+            register_global=register_global,
+            export_mode=export_mode,
+            capture_input=capture_input,
+            capture_output=capture_output,
+            mask=mask,
+            max_attribute_length=max_attribute_length,
+            span_filter=span_filter,
+            on_error=on_error,
+            disable_atexit=disable_atexit,
+            timeout=timeout,
+            span_exporter=span_exporter,
+            log_exporter=log_exporter,
+            metric_reader=metric_reader,
+        )
+    except BaseException as exc:
+        report_error(on_error, "init failed; telemetry disabled", exc)
+        client = Client(config=config, enabled=False)
+
+    with _lock:
+        previous = _client
+        _client = client
+    if previous is not None:
+        logger.warning("telemetry-dev: init() called again; replacing the previous client")
+        try:
+            previous.shutdown()
+        except BaseException as exc:
+            report_error(on_error, "failed to shut down the previous client", exc)
+    return client
+
+
+def get_client() -> Client | None:
+    return _client
+
+
+def flush(timeout_s: float = 10.0) -> None:
+    """Force-flush pending traces, logs, and metrics (serverless-friendly)."""
+    client = _client
+    if client is not None:
+        client.flush(timeout_s)
+
+
+def shutdown(timeout_s: float = 10.0) -> None:
+    """Flush and tear down the SDK; resets the singleton to uninitialized."""
+    client = _client
+    if client is not None:
+        client.shutdown(timeout_s)

telemetry_dev/_config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import logging
+import os
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+DEFAULT_BASE_URL = "https://ingest.telemetry.dev"
+
+
+def _resolve_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("telemetry-dev")
+    except Exception:  # pragma: no cover - dev tree without installed dist
+        return "0.0.0"
+
+
+SDK_VERSION = _resolve_version()
+
+LogLevelOption = Literal["debug", "info", "warn", "error", "silent"]
+
+logger = logging.getLogger("telemetry_dev")
+
+_LOG_LEVELS: dict[str, int] = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warn": logging.WARNING,
+    "error": logging.ERROR,
+    "silent": logging.CRITICAL + 1,
+}
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    api_key: str | None
+    base_url: str
+    environment: str
+    service_name: str
+
+
+def resolve_config(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    environment: str | None = None,
+    service_name: str | None = None,
+) -> ResolvedConfig:
+    url = base_url or os.environ.get("TELEMETRY_DEV_BASE_URL") or DEFAULT_BASE_URL
+    return ResolvedConfig(
+        api_key=api_key or os.environ.get("TELEMETRY_DEV_API_KEY") or None,
+        base_url=re.sub(r"/+$", "", url),
+        environment=environment or os.environ.get("TELEMETRY_DEV_ENVIRONMENT") or "production",
+        service_name=service_name or os.environ.get("OTEL_SERVICE_NAME") or "unknown_service",
+    )
+
+
+def configure_logger(log_level: LogLevelOption) -> None:
+    level = _LOG_LEVELS.get(log_level, logging.WARNING)
+    logger.setLevel(level)
+    if log_level != "silent" and not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(name)s %(levelname)s %(message)s"))
+        logger.addHandler(handler)
+
+
+def report_error(
+    on_error: Callable[[BaseException], None] | None,
+    message: str,
+    exc: BaseException,
+) -> None:
+    """Route an internal SDK error to the on_error hook + leveled logger; never raises."""
+    if on_error is not None:
+        try:
+            on_error(exc)
+        except BaseException:
+            logger.debug("telemetry-dev on_error hook raised", exc_info=True)
+    logger.error("telemetry-dev: %s", message, exc_info=exc)

telemetry_dev/_context.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from collections.abc import Generator, Mapping
+from contextlib import contextmanager
+from typing import Any, cast
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.trace import NonRecordingSpan, SpanContext
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from ._config import logger
+from ._semconv import (
+    ATTR_SESSION_ID,
+    ATTR_USER_ID,
+    METADATA_PREFIX,
+    RESERVED_METADATA_KEYS,
+)
+from ._serialize import AttributeValue, coerce_attr_value
+
+_PROPAGATED_KEY = otel_context.create_key("telemetry_dev.propagated")
+
+_PROPAGATOR = TraceContextTextMapPropagator()
+
+ParentInput = str | Context | SpanContext | None
+
+
+def propagated_attributes(context: Context | None = None) -> dict[str, AttributeValue]:
+    value = otel_context.get_value(_PROPAGATED_KEY, context=context)
+    if isinstance(value, Mapping):
+        return dict(cast("Mapping[str, AttributeValue]", value))
+    return {}
+
+
+@contextmanager
+def propagate_attributes(
+    *,
+    user_id: str | None = None,
+    session_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> Generator[None]:
+    """Stamp user.id / gen_ai.conversation.id / td.metadata.* on every span and log record
+    started inside this context. Nestable; inner values win on key conflicts."""
+    attrs = propagated_attributes()
+    if user_id is not None:
+        attrs[ATTR_USER_ID] = user_id
+    if session_id is not None:
+        attrs[ATTR_SESSION_ID] = session_id
+    if metadata is not None:
+        for key, value in metadata.items():
+            if key in RESERVED_METADATA_KEYS:
+                logger.debug(
+                    "telemetry-dev: dropping reserved metadata key %r "
+                    "(use user_id/session_id instead)",
+                    key,
+                )
+                continue
+            attr = coerce_attr_value(value, key=f"{METADATA_PREFIX}{key}")
+            if attr is not None:
+                attrs[f"{METADATA_PREFIX}{key}"] = attr
+    token = otel_context.attach(otel_context.set_value(_PROPAGATED_KEY, attrs))
+    try:
+        yield
+    finally:
+        otel_context.detach(token)
+
+
+def get_traceparent() -> str | None:
+    carrier: dict[str, str] = {}
+    _PROPAGATOR.inject(carrier)
+    return carrier.get("traceparent")
+
+
+def traceparent_of(span_context: SpanContext) -> str | None:
+    if not span_context.is_valid:
+        return None
+    return (
+        f"00-{span_context.trace_id:032x}-{span_context.span_id:016x}"
+        f"-{span_context.trace_flags:02x}"
+    )
+
+
+def context_from_parent(parent: ParentInput) -> Context | None:
+    """Resolve the `parent=` option into an OTel Context (None = current context)."""
+    if parent is None:
+        return None
+    if isinstance(parent, str):
+        # Anchor extraction on the current context: an invalid traceparent then falls back to
+        # the active span instead of silently starting a new root trace.
+        ctx = _PROPAGATOR.extract({"traceparent": parent}, context=otel_context.get_current())
+    elif isinstance(parent, SpanContext):
+        ctx = trace.set_span_in_context(NonRecordingSpan(parent))
+    else:
+        ctx = parent
+    # Preserve ambient propagated attributes when the parent is overridden explicitly.
+    if otel_context.get_value(_PROPAGATED_KEY, context=ctx) is None:
+        ambient = propagated_attributes()
+        if ambient:
+            ctx = otel_context.set_value(_PROPAGATED_KEY, ambient, context=ctx)
+    return ctx

telemetry_dev/_logs.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from opentelemetry import context as otel_context
+from opentelemetry._logs import SeverityNumber
+
+from ._client import get_client
+from ._config import logger
+from ._context import propagated_attributes
+from ._semconv import SEVERITY, LogLevel
+from ._serialize import AttributeValue, coerce_attr_value
+
+
+def log(
+    message: str,
+    *,
+    level: LogLevel = "info",
+    event_name: str | None = None,
+    attributes: Mapping[str, AttributeValue] | None = None,
+) -> None:
+    """Emit an OTLP log record to /v1/logs, correlated with the current trace context.
+    Levels: debug | info | warn | error ("warning" is accepted as an alias of "warn")."""
+    client = get_client()
+    if client is None or not client.enabled or client.otel_logger is None:
+        return
+    try:
+        normalized = "warn" if level == "warning" else level
+        severity = SEVERITY.get(normalized)
+        if severity is None:
+            logger.debug("telemetry-dev: unknown log level %r; using 'info'", level)
+            normalized, severity = "info", SEVERITY["info"]
+        attrs: dict[str, AttributeValue] = {}
+        if attributes is not None:
+            for key, value in attributes.items():
+                attr = coerce_attr_value(
+                    value,
+                    max_len=client.max_attribute_length,
+                    key=key,
+                    on_error=client.on_error,
+                )
+                if attr is not None:
+                    attrs[key] = attr
+        # Propagated correlation attrs win on key collisions, matching the span-processor
+        # stamping model and the TypeScript SDK.
+        for key, value in propagated_attributes().items():
+            attr = coerce_attr_value(
+                value,
+                max_len=client.max_attribute_length,
+                key=key,
+                on_error=client.on_error,
+            )
+            if attr is not None:
+                attrs[key] = attr
+        body = client.serialize(message, "log.message") or ""
+        client.otel_logger.emit(
+            context=otel_context.get_current(),
+            severity_number=SeverityNumber(severity),
+            severity_text=normalized.upper(),
+            body=body,
+            attributes=attrs or None,
+            event_name=event_name,
+        )
+    except BaseException as exc:
+        client.report("log() failed", exc)