agentops-otel 0.1.0__py3-none-any.whl

agentops_otel/__init__.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from agentops_otel.baggage import BaggageSpanProcessor, is_agentops_baggage_key
+from agentops_otel.logging import (
+    ConsoleFormatter,
+    CPForwardingHandler,
+    JsonFormatter,
+    TraceCorrelationFilter,
+    configure_logging,
+    get_logger,
+    is_local,
+    resolve_env,
+    resolve_log_level,
+)
+from agentops_otel.telemetry import (
+    METRIC_PREFIX,
+    TelemetrySettings,
+    configure_telemetry,
+    metric_name,
+    otlp_exporter_classes,
+    prometheus_exposition,
+    prometheus_metrics_enabled,
+    span_baggage_enabled,
+)
+
+__all__ = [
+    "METRIC_PREFIX",
+    "BaggageSpanProcessor",
+    "CPForwardingHandler",
+    "ConsoleFormatter",
+    "JsonFormatter",
+    "TelemetrySettings",
+    "TraceCorrelationFilter",
+    "configure_logging",
+    "configure_telemetry",
+    "get_logger",
+    "is_agentops_baggage_key",
+    "is_local",
+    "metric_name",
+    "otlp_exporter_classes",
+    "prometheus_exposition",
+    "prometheus_metrics_enabled",
+    "resolve_env",
+    "resolve_log_level",
+    "span_baggage_enabled",
+]

agentops_otel/baggage.py

@@ -0,0 +1,52 @@
+"""Copy OpenTelemetry baggage onto spans, so tenant/identity context set upstream reaches every span.
+
+Span attributes are not inherited by child spans, and identity is often known only after a span
+starts. Baggage solves both: it lives in the context and propagates via the W3C ``baggage`` header, so
+values set once (e.g. by the control plane's auth middleware) reach child spans **and** spans in
+downstream services in the same trace. :class:`BaggageSpanProcessor` promotes those baggage entries to
+span attributes at span start. :func:`configure_telemetry` registers it for every AgentOps service
+(control plane + workers), so a worker span is attributable to the account the control plane set.
+
+A tiny in-house equivalent of the OTel-contrib ``BaggageSpanProcessor`` (avoids a new dependency),
+scoped to the AgentOps ``agentops.*`` namespace so unrelated baggage is never promoted to a span tag.
+Only non-PII stable ids belong in baggage — it rides outbound headers to every callee, including
+external ones — so callers must never put email/name there.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from opentelemetry.baggage import get_all as get_all_baggage
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+
+logger = logging.getLogger(__name__)
+
+AGENTOPS_BAGGAGE_PREFIX = "agentops."
+
+
+def is_agentops_baggage_key(key: str) -> bool:
+    """Whether a baggage key is one AgentOps sets (and may be promoted to a span attribute)."""
+    return key.startswith(AGENTOPS_BAGGAGE_PREFIX)
+
+
+class BaggageSpanProcessor(SpanProcessor):
+    """Copy ``agentops.*`` baggage entries onto every span at start (see module docstring)."""
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        try:
+            for key, value in get_all_baggage(parent_context).items():
+                if is_agentops_baggage_key(key):
+                    span.set_attribute(key, str(value))
+        except Exception:  # noqa: BLE001 — telemetry must never break the request path
+            logger.debug("otel: BaggageSpanProcessor.on_start failed", exc_info=True)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        return None
+
+    def shutdown(self) -> None:
+        return None
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True

agentops_otel/logging.py

@@ -0,0 +1,323 @@
+"""Shared application logging for AgentOps.
+
+One entry point, :func:`configure_logging`, installs a single stdout handler on
+the root logger and picks its shape from the environment:
+
+* **Local dev** (``AGENTOPS_ENV``/``AGENTOPS_DD_ENV``/``ENV`` unset or ``local``):
+  a human-readable, coloured console line — ``time LEVEL name file:line message``.
+* **Everything else** (``staging``, ``production``, …): one-line JSON per event
+  with the explicit ``level``/``status`` and ``dd.*`` fields Datadog reads, so a
+  Datadog agent tailing container stdout ingests correct severity and correlates
+  logs to traces.
+
+Trace correlation is *generic OpenTelemetry*: we read the current span through
+the OTel API only. When no tracer/exporter is configured (the common case —
+``configure_telemetry`` is opt-in) ``get_current_span`` returns an invalid span
+and we add nothing, so there is no dependency on a running collector. When a
+span *is* active, we emit both ``otelTraceID``/``otelSpanID`` and the
+``dd.trace_id``/``dd.span_id`` (lower-64-bit) form Datadog uses.
+
+Every module gets its logger with :func:`get_logger` (a thin
+``logging.getLogger`` wrapper); logs propagate to the single root handler.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import traceback
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+
+try:  # OTel API is a dependency of this package; guard only for extreme trimmed installs.
+    from opentelemetry import trace
+except ImportError:  # pragma: no cover - opentelemetry-api is always present in practice
+    trace = None  # type: ignore[assignment]
+
+__all__ = [
+    "CPForwardingHandler",
+    "ConsoleFormatter",
+    "JsonFormatter",
+    "TraceCorrelationFilter",
+    "configure_logging",
+    "get_logger",
+    "is_local",
+    "resolve_env",
+    "resolve_log_level",
+]
+
+DEFAULT_LOG_LEVEL = "INFO"
+_LOCAL_ENV = "local"
+# Environments that should get the readable console formatter rather than JSON.
+_LOCAL_ENVS = frozenset({"", _LOCAL_ENV, "dev", "development", "test"})
+
+# Env vars checked, in order, to decide which environment we run in. The first
+# non-empty wins. ``AGENTOPS_DD_ENV`` is set to ``staging``/``production`` on our
+# deployments (Helm plain env), which makes deployed pods emit JSON automatically.
+_ENV_KEYS = ("AGENTOPS_ENV", "AGENTOPS_DD_ENV", "ENV")
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+# Attributes present on a bare LogRecord — anything else in ``record.__dict__`` is
+# caller-supplied structured context (``extra={...}``) worth rendering.
+_RESERVED_LOG_ATTRS = frozenset(logging.makeLogRecord({}).__dict__)
+# Correlation/derived keys we render in their own slot, never as generic extras.
+_CORRELATION_KEYS = frozenset({"otelTraceID", "otelSpanID", "dd.trace_id", "dd.span_id"})
+_CONSOLE_SKIP = _RESERVED_LOG_ATTRS | _CORRELATION_KEYS | {"message", "dd.service", "dd.env", "dd.version"}
+
+_ROOT_CONFIGURED_FLAG = "_agentops_logging_configured"
+
+
+def resolve_env(env: Mapping[str, str] | None = None) -> str:
+    """Return the lower-cased environment name (``local`` when nothing is set)."""
+    env = env if env is not None else os.environ
+    for key in _ENV_KEYS:
+        value = (env.get(key) or "").strip().lower()
+        if value:
+            return value
+    return _LOCAL_ENV
+
+
+def is_local(env: Mapping[str, str] | None = None) -> bool:
+    """True when the environment name is local/dev/test (ignores telemetry signals)."""
+    return resolve_env(env) in _LOCAL_ENVS
+
+
+def _prefer_json(env: Mapping[str, str]) -> bool:
+    """Default to JSON when deployed.
+
+    ``is_local`` alone is not enough: our worker pods set an OTLP endpoint but no
+    environment name, so we also treat a configured OTLP endpoint (or
+    ``AGENTOPS_OTEL_ENABLED``) as a deployed signal.
+    """
+    if not is_local(env):
+        return True
+    if (env.get("OTEL_EXPORTER_OTLP_ENDPOINT") or "").strip():
+        return True
+    return (env.get("AGENTOPS_OTEL_ENABLED") or "").strip().lower() in _TRUTHY
+
+
+def resolve_log_level(name: str) -> int:
+    """Map a level name (e.g. ``"INFO"``) to its int, falling back to INFO.
+
+    Intentionally shared: ``telemetry.py`` reuses it for the OTLP log handler.
+    """
+    level = logging.getLevelName(name)
+    return level if isinstance(level, int) else logging.INFO
+
+
+def _coerce_level(level: int | str) -> int:
+    return level if isinstance(level, int) else resolve_log_level(level.strip().upper())
+
+
+def _effective_level(level: int | str | None, env: Mapping[str, str]) -> int:
+    """Resolve the root level: explicit arg > ``AGENTOPS_LOG_LEVEL`` > debug flag > INFO."""
+    if level is not None:
+        return _coerce_level(level)
+    name = (env.get("AGENTOPS_LOG_LEVEL") or "").strip()
+    if name:
+        return resolve_log_level(name.upper())
+    if (env.get("AGENTOPS_DEBUG") or "").strip().lower() in _TRUTHY:
+        return logging.DEBUG
+    return resolve_log_level(DEFAULT_LOG_LEVEL)
+
+
+def _datadog_tags(env: Mapping[str, str]) -> dict[str, str]:
+    """Datadog unified-service tags to stamp on every JSON log, when configured."""
+    tags: dict[str, str] = {}
+    service = env.get("OTEL_SERVICE_NAME") or env.get("AGENTOPS_SERVICE_NAME")
+    version = env.get("OTEL_SERVICE_VERSION") or env.get("AGENTOPS_VERSION")
+    dd_env = env.get("AGENTOPS_DD_ENV") or env.get("AGENTOPS_ENV")
+    if service:
+        tags["dd.service"] = service
+    if version:
+        tags["dd.version"] = version
+    if dd_env:
+        tags["dd.env"] = dd_env
+    return tags
+
+
+def _extra_fields(record: logging.LogRecord, skip: frozenset[str]) -> dict[str, object]:
+    return {k: v for k, v in record.__dict__.items() if k not in skip}
+
+
+class TraceCorrelationFilter(logging.Filter):
+    """Stamp OTel/Datadog trace-correlation ids onto records from the active span.
+
+    Uses only the OpenTelemetry *API*: when no SDK/exporter is active the current
+    span is invalid and we add no correlation ids — so this is safe to install
+    unconditionally and needs no running collector.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if trace is None:
+            return True
+        # get_current_span() always returns a Span (INVALID_SPAN when none is active).
+        ctx = trace.get_current_span().get_span_context()
+        if ctx.is_valid:
+            record.otelTraceID = format(ctx.trace_id, "032x")
+            record.otelSpanID = format(ctx.span_id, "016x")
+            # Datadog reads the lower 64 bits of the trace id as a decimal string.
+            record.__dict__["dd.trace_id"] = str(ctx.trace_id & 0xFFFFFFFFFFFFFFFF)
+            record.__dict__["dd.span_id"] = str(ctx.span_id)
+        return True
+
+
+class JsonFormatter(logging.Formatter):
+    """One-line JSON per event with explicit level/status so Datadog reads severity.
+
+    ``static_tags`` (Datadog unified-service ``dd.service``/``dd.env``/``dd.version``)
+    are stamped on every event; per-record trace ids come from
+    :class:`TraceCorrelationFilter`.
+    """
+
+    def __init__(self, static_tags: Mapping[str, str] | None = None) -> None:
+        super().__init__()
+        self._static_tags = dict(static_tags or {})
+
+    def format(self, record: logging.LogRecord) -> str:
+        logger_info: dict[str, str] = {"name": record.name}
+        if record.threadName:
+            logger_info["thread_name"] = record.threadName
+        payload: dict[str, object] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "status": record.levelname,
+            "message": record.getMessage(),
+            "logger": logger_info,
+        }
+        if record.exc_info:
+            exc_type, exc_value, _ = record.exc_info
+            payload["error"] = {
+                "kind": exc_type.__name__ if exc_type is not None else None,
+                "message": str(exc_value) if exc_value is not None else None,
+                "stack": self.formatException(record.exc_info),
+            }
+        elif record.exc_text:
+            payload["error"] = {"stack": record.exc_text}
+        if record.stack_info:
+            logger_info["stack_info"] = self.formatStack(record.stack_info)
+        for attr in ("otelTraceID", "otelSpanID"):
+            value = getattr(record, attr, None)
+            if value and value != "0":
+                payload[attr] = value
+        for key, value in record.__dict__.items():
+            if key not in _RESERVED_LOG_ATTRS and key not in payload:
+                payload[key] = value
+        for key, value in self._static_tags.items():
+            payload.setdefault(key, value)
+        return json.dumps(payload, default=str)
+
+
+_LEVEL_COLORS = {
+    logging.DEBUG: "\x1b[36m",  # cyan
+    logging.INFO: "\x1b[32m",  # green
+    logging.WARNING: "\x1b[33m",  # yellow
+    logging.ERROR: "\x1b[31m",  # red
+    logging.CRITICAL: "\x1b[1;41m",  # bold on red
+}
+_DIM = "\x1b[2m"
+_RESET = "\x1b[0m"
+
+
+class ConsoleFormatter(logging.Formatter):
+    """Readable single-line dev output: ``time LEVEL name file:line message k=v``."""
+
+    def __init__(self, *, use_color: bool) -> None:
+        super().__init__(datefmt="%H:%M:%S")
+        self._use_color = use_color
+
+    def _paint(self, text: str, color: str) -> str:
+        return f"{color}{text}{_RESET}" if self._use_color else text
+
+    def format(self, record: logging.LogRecord) -> str:
+        ts = f"{self.formatTime(record, self.datefmt)}.{int(record.msecs):03d}"
+        level = self._paint(f"{record.levelname:<8}", _LEVEL_COLORS.get(record.levelno, ""))
+        location = self._paint(f"{record.name} {os.path.basename(record.pathname)}:{record.lineno}", _DIM)
+        parts = [self._paint(ts, _DIM), level, location, record.getMessage()]
+        extras = _extra_fields(record, _CONSOLE_SKIP)
+        if extras:
+            parts.append(self._paint(" ".join(f"{k}={v}" for k, v in extras.items()), _DIM))
+        line = " ".join(parts)
+        if record.exc_info:
+            line += "\n" + self.formatException(record.exc_info)
+        if record.stack_info:
+            line += "\n" + self.formatStack(record.stack_info)
+        return line
+
+
+class CPForwardingHandler(logging.Handler):
+    # sink is injected so this stays free of any control-plane client dependency.
+    def __init__(self, sink: Callable[[str, str, str], None]) -> None:
+        super().__init__()
+        self._sink = sink
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            message = record.getMessage()
+            if record.exc_info:
+                message = f"{message}\n{''.join(traceback.format_exception(*record.exc_info))}"
+            self._sink(message, record.levelname, record.name)
+        except Exception:
+            self.handleError(record)
+
+
+def configure_logging(
+    level: int | str | None = None,
+    *,
+    json_logs: bool | None = None,
+    env: Mapping[str, str] | None = None,
+    force: bool = False,
+) -> None:
+    """Install the single root stdout handler for this process. Idempotent.
+
+    Args:
+        level: Explicit root level. Defaults to ``AGENTOPS_LOG_LEVEL``, then
+            ``AGENTOPS_DEBUG`` (DEBUG when truthy), then INFO.
+        json_logs: Force JSON (``True``) or console (``False``). Defaults to JSON
+            in any non-local environment (or when an OTLP endpoint is configured)
+            and console locally.
+        env: Environment mapping to read (defaults to ``os.environ``); handy for
+            tests.
+        force: Reconfigure even if a previous call already set up logging.
+    """
+    root = logging.getLogger()
+    if getattr(root, _ROOT_CONFIGURED_FLAG, False) and not force:
+        return
+
+    env_map = env if env is not None else os.environ
+    use_json = _prefer_json(env_map) if json_logs is None else json_logs
+    resolved_level = _effective_level(level, env_map)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(logging.DEBUG)
+    if use_json:
+        handler.setFormatter(JsonFormatter(_datadog_tags(env_map)))
+    else:
+        handler.setFormatter(ConsoleFormatter(use_color=_should_color(env_map)))
+    handler.addFilter(TraceCorrelationFilter())
+
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+    root.addHandler(handler)
+    root.setLevel(resolved_level)
+    logging.captureWarnings(True)
+    setattr(root, _ROOT_CONFIGURED_FLAG, True)
+
+
+def _should_color(env: Mapping[str, str]) -> bool:
+    if (env.get("NO_COLOR") or "").strip():
+        return False
+    if (env.get("FORCE_COLOR") or "").strip():
+        return True
+    return sys.stdout.isatty()
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a standard logger for ``name`` (use ``get_logger(__name__)``).
+
+    Records propagate to the single root handler installed by
+    :func:`configure_logging`, so no per-module handler wiring is needed.
+    """
+    return logging.getLogger(name)

agentops_otel/telemetry.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry import metrics, trace
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
+    OTLPLogExporter as GrpcLogExporter,
+)
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+    OTLPMetricExporter as GrpcMetricExporter,
+)
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+    OTLPSpanExporter as GrpcSpanExporter,
+)
+from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+    OTLPLogExporter as HttpLogExporter,
+)
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+    OTLPMetricExporter as HttpMetricExporter,
+)
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+    OTLPSpanExporter as HttpSpanExporter,
+)
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from opentelemetry.instrumentation.logging import LoggingInstrumentor
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+try:
+    from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+except ImportError:  # pragma: no cover - only reachable when the [sqlalchemy] extra is not installed
+    SQLAlchemyInstrumentor = None  # type: ignore[assignment, misc]
+
+try:
+    from opentelemetry.exporter.prometheus import PrometheusMetricReader
+    from prometheus_client import CONTENT_TYPE_LATEST, REGISTRY, generate_latest
+except ImportError:  # pragma: no cover - only reachable when the [prometheus] extra is not installed
+    PrometheusMetricReader = None  # type: ignore[assignment, misc]
+
+from agentops_otel.baggage import BaggageSpanProcessor
+from agentops_otel.logging import DEFAULT_LOG_LEVEL, resolve_log_level
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import AsyncEngine
+
+logger = logging.getLogger(__name__)
+
+# Every AgentOps metric lives under this single namespace root so the whole product's metrics are
+# isolated and trivially sliceable in Datadog (``agentops.*``). Names go through :func:`metric_name`
+# at instrument-creation time; there is no SDK-level global rewrite (OTel Python has no dynamic
+# per-instrument prefixing View), so this helper is the shared convention all metric sites use.
+METRIC_PREFIX = "agentops."
+
+
+def metric_name(name: str) -> str:
+    """Return ``name`` under the canonical ``agentops.`` metric namespace.
+
+    Idempotent: a name that already starts with :data:`METRIC_PREFIX` is returned unchanged, so
+    callers may pass either the bare suffix (``"authz.pdp.duration_ms"``) or the full name safely.
+    """
+    return name if name.startswith(METRIC_PREFIX) else f"{METRIC_PREFIX}{name}"
+
+
+DEFAULT_PROTOCOL = "http/protobuf"
+
+_configured = False
+_prometheus_enabled = False
+
+
+@dataclass(frozen=True)
+class TelemetrySettings:
+    """Resolved OpenTelemetry configuration for AgentOps components.
+
+    Activation is opt-in: telemetry is enabled only when an OTLP endpoint is
+    configured or AGENTOPS_OTEL_ENABLED is truthy. All transport details
+    (endpoint, headers, sampling) are read directly by the OTel exporters from
+    standard OTEL_* env vars; this object only captures what our code branches on.
+    """
+
+    enabled: bool
+    protocol: str
+    service_name: str
+    log_level: str
+    logs_enabled: bool
+    baggage_enabled: bool
+
+    @classmethod
+    def from_env(
+        cls,
+        env: Mapping[str, str] | None = None,
+        *,
+        default_service_name: str,
+    ) -> TelemetrySettings:
+        """Build a TelemetrySettings from environment variables.
+
+        Args:
+            env: Optional mapping to read from (defaults to os.environ).
+            default_service_name: Fallback service name when OTEL_SERVICE_NAME
+                is not set. Required and keyword-only — each caller supplies its
+                own service name so no component silently inherits an empty one.
+        """
+        env = env if env is not None else os.environ
+        endpoint = env.get("OTEL_EXPORTER_OTLP_ENDPOINT") or ""
+        flag = (env.get("AGENTOPS_OTEL_ENABLED") or "").strip().lower()
+        enabled = bool(endpoint) or flag in {"1", "true", "yes", "on"}
+        protocol = (env.get("OTEL_EXPORTER_OTLP_PROTOCOL") or DEFAULT_PROTOCOL).strip()
+        service_name = env.get("OTEL_SERVICE_NAME") or default_service_name
+        log_level = (env.get("AGENTOPS_OTEL_LOG_LEVEL") or DEFAULT_LOG_LEVEL).strip().upper()
+        # OTLP log export is opt-out; disable where the collector rejects /v1/logs.
+        logs_enabled = (env.get("AGENTOPS_OTEL_LOGS_ENABLED") or "true").strip().lower() in {"1", "true", "yes", "on"}
+        return cls(
+            enabled=enabled,
+            protocol=protocol,
+            service_name=service_name,
+            log_level=log_level,
+            logs_enabled=logs_enabled,
+            baggage_enabled=span_baggage_enabled(env),
+        )
+
+
+def otlp_exporter_classes(protocol: str) -> tuple[type, type, type]:
+    """Return (span_exporter, metric_exporter, log_exporter) classes for a protocol.
+
+    Each exporter reads its endpoint, headers, and timeout from standard OTEL_*
+    env vars at instantiation, so callers construct them with no arguments.
+    """
+    if protocol == "grpc":
+        return GrpcSpanExporter, GrpcMetricExporter, GrpcLogExporter
+
+    return HttpSpanExporter, HttpMetricExporter, HttpLogExporter
+
+
+def span_baggage_enabled(env: Mapping[str, str] | None = None) -> bool:
+    """Whether baggage→span copying is enabled (opt-out env flag, default on).
+
+    Read both here (to register :class:`BaggageSpanProcessor`) and by callers that *set* baggage —
+    e.g. the control plane's auth middleware — so the set and the processor share one switch.
+    """
+    env = env if env is not None else os.environ
+    return (env.get("AGENTOPS_OTEL_SPAN_BAGGAGE_ENABLED") or "true").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def configure_telemetry(
+    service_name: str,
+    *,
+    app: FastAPI | None = None,
+    engine: AsyncEngine | None = None,
+    resource_attributes: Mapping[str, str] | None = None,
+) -> bool:
+    """Initialize OpenTelemetry for an AgentOps component.
+
+    Returns True if telemetry was activated, False if disabled or already
+    configured. ``resource_attributes`` are merged onto every span, metric,
+    and log record.
+    """
+    global _configured, _prometheus_enabled
+    if _configured:
+        return False
+
+    settings = TelemetrySettings.from_env(default_service_name=service_name)
+    prometheus_on = _prometheus_flag_set()
+    if not settings.enabled and not prometheus_on:
+        return False
+
+    attrs: dict[str, str] = {"service.name": settings.service_name}
+    if resource_attributes:
+        attrs.update(resource_attributes)
+    resource = Resource.create(attrs)
+
+    metric_readers: list[Any] = []
+    if settings.enabled:
+        span_exporter_cls, metric_exporter_cls, log_exporter_cls = otlp_exporter_classes(settings.protocol)
+        tracer_provider = TracerProvider(resource=resource)
+        tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter_cls()))
+        if settings.baggage_enabled:
+            # Promote agentops.* baggage (tenant/identity ids set upstream) onto every span, incl.
+            # spans in this service that continue a trace started elsewhere. Set-side lives in the
+            # service that has the identity (e.g. controlplane auth middleware).
+            tracer_provider.add_span_processor(BaggageSpanProcessor())
+        trace.set_tracer_provider(tracer_provider)
+        metric_readers.append(PeriodicExportingMetricReader(metric_exporter_cls()))
+
+    if prometheus_on:
+        prometheus_reader = _make_prometheus_reader()
+        if prometheus_reader is not None:
+            metric_readers.append(prometheus_reader)
+            _prometheus_enabled = True
+
+    meter_provider = MeterProvider(resource=resource, metric_readers=metric_readers)
+    metrics.set_meter_provider(meter_provider)
+
+    if settings.enabled and settings.logs_enabled:
+        logger_provider = LoggerProvider(resource=resource)
+        logger_provider.add_log_record_processor(BatchLogRecordProcessor(log_exporter_cls()))
+        set_logger_provider(logger_provider)
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", message=".*LoggingHandler.*deprecated.*", category=DeprecationWarning)
+            otlp_handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider)
+        otlp_handler.addFilter(lambda record: not record.name.startswith("opentelemetry"))
+        root_logger = logging.getLogger()
+        root_logger.addHandler(otlp_handler)
+        root_logger.setLevel(resolve_log_level(settings.log_level))
+
+    if settings.enabled:
+        _instrument(app, engine)
+
+    _configured = True
+    logger.info(
+        "opentelemetry: enabled (otlp=%s prometheus=%s service=%s)",
+        settings.enabled,
+        _prometheus_enabled,
+        settings.service_name,
+    )
+    return True
+
+
+def _prometheus_flag_set(env: Mapping[str, str] | None = None) -> bool:
+    env = env if env is not None else os.environ
+    return (env.get("AGENTOPS_PROMETHEUS_METRICS") or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _make_prometheus_reader() -> object | None:
+    if PrometheusMetricReader is None:
+        logger.warning("opentelemetry-exporter-prometheus not installed; /metrics disabled")
+        return None
+    return PrometheusMetricReader()
+
+
+def prometheus_metrics_enabled() -> bool:
+    """True when a Prometheus reader is active and /metrics can be served."""
+    return _prometheus_enabled
+
+
+def prometheus_exposition() -> tuple[bytes, str]:
+    """Return (payload, content_type) of the current Prometheus metrics exposition."""
+    if PrometheusMetricReader is None:
+        raise RuntimeError("prometheus_client / opentelemetry-exporter-prometheus not installed; /metrics unavailable")
+    return generate_latest(REGISTRY), CONTENT_TYPE_LATEST
+
+
+def _instrument(app: FastAPI | None, engine: AsyncEngine | None) -> None:
+    """Run the auto-instrumentors.
+
+    The module-level ``_configured`` flag in ``configure_telemetry`` guards
+    against double-instrumentation (``FastAPIInstrumentor.instrument_app`` is
+    per-app and would otherwise stack middleware on repeat calls).
+    """
+    HTTPXClientInstrumentor().instrument()
+    LoggingInstrumentor().instrument(set_logging_format=False)
+    if app is not None:
+        try:
+            from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor  # noqa: PLC0415
+        except ImportError as exc:  # pragma: no cover - only hit without fastapi
+            raise RuntimeError(
+                "configure_telemetry(app=...) requires fastapi; install it "
+                "(e.g. `pip install fastapi`) or call configure_telemetry() without an app."
+            ) from exc
+        # Health probes fire constantly (k8s liveness/readiness) and carry no
+        # signal — drop their spans so we don't waste export volume on them.
+        FastAPIInstrumentor.instrument_app(app, excluded_urls="healthz")
+    if engine is not None and SQLAlchemyInstrumentor is not None:
+        SQLAlchemyInstrumentor().instrument(engine=engine.sync_engine)

agentops_otel-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: agentops-otel
+Version: 0.1.0
+Summary: Shared OpenTelemetry bootstrap for AgentOps (control plane + SDK workers).
+Author: Komodor Ltd.
+License-Expression: LicenseRef-Komodor-Proprietary
+Project-URL: Homepage, https://agentops.komodor.com
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: opentelemetry-sdk>=1.27
+Requires-Dist: opentelemetry-exporter-otlp>=1.27
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0
+Requires-Dist: opentelemetry-instrumentation-logging>=0.48b0
+Provides-Extra: sqlalchemy
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == "sqlalchemy"
+Provides-Extra: prometheus
+Requires-Dist: opentelemetry-exporter-prometheus>=0.48b0; extra == "prometheus"
+Dynamic: license-file
+
+# agentops-otel
+
+Shared logging + OpenTelemetry bootstrap for AgentOps.
+
+## Logging (`configure_logging`, `get_logger`)
+
+One entry point sets up the process's logging; every module then grabs a logger
+and lets records propagate to the single root handler:
+
+```python
+from agentops_otel import configure_logging, get_logger
+
+configure_logging()          # once, at process start (idempotent)
+log = get_logger(__name__)   # in every module
+log.info("worker started", extra={"worker_id": wid})
+```
+
+`configure_logging()` installs **one** stdout handler on the root logger and
+picks its shape from the environment:
+
+- **Local** (`AGENTOPS_ENV` / `AGENTOPS_DD_ENV` / `ENV` unset or `local`) — a
+  readable, coloured console line: `time LEVEL name file:line message key=val`.
+- **Anything else** (`staging`, `production`, …) — one-line JSON per event with
+  explicit `level`/`status` and Datadog unified-service `dd.*` tags, so a Datadog
+  agent tailing container stdout reads the real severity and correlates to traces.
+
+Our staging/prod control plane sets `AGENTOPS_DD_ENV`, and worker pods set
+`OTEL_EXPORTER_OTLP_ENDPOINT` — either signal flips a deployed process to JSON
+automatically, with no extra config. Overrides: `json_logs=True|False` forces a
+format; level comes from the arg, then `AGENTOPS_LOG_LEVEL`, then
+`AGENTOPS_DEBUG`, then INFO.
+
+**Trace correlation is generic OpenTelemetry.** We read the current span through
+the OTel *API* only. When no tracer/exporter is configured (the default —
+`configure_telemetry` is opt-in), there is no active span and nothing is added,
+so logging needs no running collector. When a span *is* active, each JSON record
+gains `otelTraceID`/`otelSpanID` plus the `dd.trace_id`/`dd.span_id`
+(lower-64-bit) form Datadog uses.
+
+### Forwarding worker logs to the control plane (`CPForwardingHandler`)
+
+`agentops_otel.CPForwardingHandler` bridges the standard logging module to a
+sink callback — the SDK worker runtime (`komodor_agentops.worker.logging_bridge.install_cp_log_forwarding`)
+uses it to also ship every worker log record to the control plane as a
+`log.created` event, since Komodor has no pod/log access to customer-hosted
+workers. Two env vars control it:
+
+- `AGENTOPS_CP_LOG_LEVEL` (default `INFO`) — minimum level forwarded to CP.
+- `AGENTOPS_CP_LOG_CAPTURE_ALL` (default off) — forward only the SDK's own
+  loggers (`komodor_agentops`, `agentops`) when unset; set to attach to the
+  root logger instead and capture the whole process.
+
+## Telemetry (`configure_telemetry`)
+
+`configure_telemetry(service_name, *, app=None, engine=None)` builds OTLP
+tracer/meter/logger providers (HTTP/protobuf or gRPC), attaches the OTel logging
+handler, and runs the FastAPI / httpx / logging auto-instrumentors. SQLAlchemy
+instrumentation is the optional `agentops-otel[sqlalchemy]` extra.
+
+Off by default: nothing is installed unless `OTEL_EXPORTER_OTLP_ENDPOINT` or
+`AGENTOPS_OTEL_ENABLED` is set. Used by the control plane and by the SDK worker
+runtime; neither duplicates the setup.
+
+## Metric naming (`metric_name`, `METRIC_PREFIX`)
+
+Every AgentOps metric lives under a single `agentops.` namespace root so the
+whole product's metrics are isolated and trivially sliceable in Datadog. **When
+you create an instrument, name it through `metric_name()`** rather than passing a
+raw string:
+
+```python
+from agentops_otel import metric_name
+from opentelemetry import metrics
+
+meter = metrics.get_meter("agentops.controlplane.authz")
+hist = meter.create_histogram(metric_name("authz.pdp.duration_ms"), unit="ms")
+# → exported as "agentops.authz.pdp.duration_ms"
+```
+
+`metric_name()` is **idempotent** — a name that already starts with
+`METRIC_PREFIX` (`"agentops."`) is returned unchanged, so passing either the bare
+suffix or the full name is safe.
+
+Why a helper and not a global rewrite? OpenTelemetry Python has no
+View/exporter-level facility for *dynamic per-instrument* renaming (a wildcard
+`View`'s `name` is a single static string), so the exported metric name is fixed
+at instrument creation. This helper is therefore the one canonical entry point.
+Note that the meter/instrumentation-scope name is separate from the metric name
+and does not affect it — the `agentops.` prefix must be on the instrument name.

agentops_otel-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentops_otel/__init__.py,sha256=_g-8fpvvGa2C72iw5afy2U4wUz2yoLxQ9Hb5dIVTBkU,1068
+agentops_otel/baggage.py,sha256=k0LvALiJGs-pjae9yCEpw8IlcwNWeFsZK8FnIDI2Qtg,2363
+agentops_otel/logging.py,sha256=f1uBD6v3bqz8BdB0Eh-48SBxQz1y7TSAqQXHv6sgIrw,12935
+agentops_otel/telemetry.py,sha256=cz9H0GR28OlJ6i9-6CAaOiK1bugcRQJh5XAUDQ1jvRk,11733
+agentops_otel-0.1.0.dist-info/licenses/LICENSE,sha256=tk2w5qlj6wMGprpSF4kOWoOh7BZsjGEUSFcGiQcVKkY,3390
+agentops_otel-0.1.0.dist-info/METADATA,sha256=f4qqEp9XvNyncQ8oIgDhJgzBs4VTUk7AwVHZBF1yv1I,5158
+agentops_otel-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agentops_otel-0.1.0.dist-info/top_level.txt,sha256=9NjNRA4d5_06lq36hkhwbu5cIZ5XFjMIttGa4BUJLQU,14
+agentops_otel-0.1.0.dist-info/RECORD,,

agentops_otel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentops_otel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,53 @@
+Komodor AgentOps License
+
+The Komodor AgentOps SDK, together with its associated libraries, documentation,
+and files (the "Software"), is provided by Komodor Ltd. ("Komodor") for integration
+with the Komodor service (the "Service"). By installing, copying, or using the
+Software, you agree to these terms.
+
+© 2020 - Komodor Ltd.
+
+Grant. Subject to your compliance with these terms, Komodor grants you a
+non-exclusive, non-transferable, non-sublicensable, worldwide, revocable, and
+limited license to (a) install and use the Software to develop, test, and operate
+integrations of your applications and services with the Service, or to use
+applications and services that embed the Software, and (b) reproduce
+and distribute verbatim copies of the Software, but only as embedded within your own
+applications, services, or container images, and not on a standalone basis. No
+separate agreement with Komodor is required; anyone who obtains the Software
+receives this license. If you have a separate written agreement with Komodor
+covering the Software, that agreement controls to the extent of any conflict.
+
+You may develop and operate your own software that imports, calls, subclasses,
+configures, or otherwise depends on the Software through its published interfaces;
+doing so is permitted use and does not, by itself, create a modified version or
+derivative work of the Software.
+
+Restrictions. You shall not: (a) distribute the Software on a standalone basis, or
+resell, lease, or sublicense it; (b) offer the Software itself, or substantially its
+standalone functionality, to third parties as a hosted or managed service — this
+does not restrict you from operating or offering your own applications or services
+that embed the Software; (c) modify the Software or create a derivative work of its
+files or code; (d) remove, alter, or obscure any copyright, license, or proprietary
+notice, all of which you must retain in every copy you distribute; or (e) claim any
+proprietary interest in the Software, or contest or infringe Komodor's intellectual
+property rights in it.
+
+Ownership. The Software is licensed, not sold. Komodor retains all right, title, and
+interest in and to the Software and all intellectual property rights in it. No
+rights are granted except as expressly stated here, and no patent rights are
+granted. This license does not permit use of Komodor's names or trademarks, except
+for reasonable and customary use in describing the origin of the Software.
+
+Termination. This license terminates automatically if you breach it and do not cure
+the breach within thirty (30) days of Komodor's written notice. On termination you
+must stop installing, using, and distributing the Software, except that copies
+already embedded in products you distributed to end users before termination may
+remain in use. The Restrictions and this "No warranty; no liability" section survive termination.
+
+No warranty; no liability. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. IN NO EVENT SHALL
+KOMODOR OR THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT
+OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

agentops_otel-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentops_otel