agentops-otel 0.1.0__tar.gz

agentops_otel-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,89 @@
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "agentops-otel"
+version = "0.1.0"
+description = "Shared OpenTelemetry bootstrap for AgentOps (control plane + SDK workers)."
+readme = "README.md"
+license = "LicenseRef-Komodor-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "Komodor Ltd." }]
+requires-python = ">=3.11"
+dependencies = [
+  # HTTPXClientInstrumentor is instrumented unconditionally in configure_telemetry,
+  # and opentelemetry-instrumentation-httpx imports httpx at module load — so httpx
+  # is a genuine runtime requirement, not optional. (fastapi is not: it's imported
+  # lazily and only when configure_telemetry(app=...) is called.)
+  "httpx",
+  "opentelemetry-sdk>=1.27",
+  "opentelemetry-exporter-otlp>=1.27",
+  "opentelemetry-instrumentation-fastapi>=0.48b0",
+  "opentelemetry-instrumentation-httpx>=0.48b0",
+  "opentelemetry-instrumentation-logging>=0.48b0",
+]
+
+[project.urls]
+Homepage = "https://agentops.komodor.com"
+
+[project.optional-dependencies]
+sqlalchemy = [
+  "opentelemetry-instrumentation-sqlalchemy>=0.48b0",
+]
+prometheus = [
+  "opentelemetry-exporter-prometheus>=0.48b0",
+]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+  "fastapi",
+  "pytest>=8",
+]

agentops_otel-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentops_otel-0.1.0/src/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-0.1.0/src/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