Juntai Observability Python

简体中文

juntai-observability is Juntai's side-effect-free Python integration for standard OpenTelemetry logs, metrics, traces, and W3C propagation. It owns bootstrap, correlation conventions, redaction, bounded metric attributes, and deterministic test utilities. It does not own telemetry storage, queries, dashboards, backend credentials, product health semantics, or usage metering.

Install and configure

python -m pip install 'juntai-observability>=2,<3'

Configure exactly once at the application composition root. Importing the package does not install providers, replace logging classes, register exporters, start threads, or register shutdown hooks.

from juntai.observability import ObservabilityConfig, configure_observability

observability = configure_observability(
    ObservabilityConfig.from_env(
        service_namespace="juntai.axiom",
        service_name="driver",
        service_version="2.4.1",
        metric_attribute_allowlist={
            "axiom.execution.requests": {"result", "mode"},
        },
    )
)

logger = observability.logger(__name__)
tracer = observability.tracer(__name__)
meter = observability.meter(__name__)

try:
    run_service()
finally:
    observability.shutdown(timeout=5.0)

Repeated identical configuration returns the same runtime. A conflicting configuration or configuration after shutdown raises ObservabilityConfigurationError during startup.

Environment contract

• OTEL_EXPORTER_OTLP_ENDPOINT normally points to the platform sidecar at http://127.0.0.1:4318.
• OTEL_EXPORTER_OTLP_PROTOCOL is http/protobuf or grpc.
• OTEL_SERVICE_NAME is the registered service name.
• OTEL_RESOURCE_ATTRIBUTES supplies service.namespace, service.version, deployment.environment.name, and optionally service.instance.id and juntai.artifact.digest.
• OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG come from the environment profile.

Application containers do not receive central backend credentials. Kubernetes resource attributes are added by the Collector, not accepted from application environment parsing.

Logging and correlation

ObservabilityRuntime.logger(name) returns a standard logging.Logger with an OpenTelemetry handler attached only to that logger. Active trace_id and span_id are supplied by OpenTelemetry. Structured extras are redacted and bounded before export.

from juntai.observability import bind_context

with bind_context(
    tenant_id=verified_tenant_id,
    tenant_verified=True,
    application_id=application_id,
    workflow_id=workflow_id,
    execution_id=execution_id,
):
    with tracer.start_as_current_span("axiom.execute"):
        logger.info("execution completed", extra={"execution.result": "succeeded"})

Only approved correlation baggage is injected or extracted. Tenant context must be explicitly verified. Secret-like keys and values, connection strings, credentials, and oversized values are removed or bounded before export.

Metrics

Meters and instruments implement standard OpenTelemetry interfaces. Metric points are dropped without failing the business operation when they contain prohibited high-cardinality keys, undeclared keys for a configured instrument, oversized values, too many labels, or more distinct attribute sets than the configured bound.

requests = meter.create_counter(
    "axiom.execution.requests",
    unit="{request}",
    description="Execution requests accepted by the driver",
)
requests.add(1, {"result": "accepted", "mode": "batch"})

Do not use tenant, user, application, workflow, execution, request, trace, raw URL, exception message, or free-form text values as metric attributes.

Deterministic tests

InMemoryObservability uses real SDK providers with in-memory exporters and no network or process-global mutation.

from juntai.observability import InMemoryObservability

telemetry = InMemoryObservability(
    service_namespace="juntai.axiom",
    service_name="driver",
)

with telemetry.tracer("test").start_as_current_span("axiom.execute"):
    telemetry.logger("test").warning("completed")

assert telemetry.logs[0].trace_id == telemetry.spans[0].trace_id
telemetry.shutdown()

The machine-readable convention is conventions/observability.v1.json. See DEVELOPMENT.md for build, contract, and real Collector acceptance commands.

Compatibility and ownership

Generic v1 imports from juntai.core.observability_tools remain as an explicit, deprecated adapter for one release. The adapter never replaces the process-wide logger class. Usage APIs are not compatible exports; install juntai-usage.

Raw telemetry is explored with the selected backend's native interfaces. Product domains own dashboards, alert interpretation, durable business state, and health actions.