Metadata-Version: 2.5
Name: juntai-observability
Version: 2.0.4
Summary: Side-effect-free OpenTelemetry bootstrap and conventions for Juntai Python services
Project-URL: Homepage, https://github.com/zephytiju/JuntaiObservabilityTools
Project-URL: Repository, https://github.com/zephytiju/JuntaiObservabilityTools.git
Project-URL: Documentation, https://github.com/zephytiju/JuntaiObservabilityTools#readme
Author-email: Juntai Team <dev@juntai.com>
License: PROPRIETARY SOFTWARE LICENSE AGREEMENT
        
        Copyright (c) 2024-2026 Juntai Team. All rights reserved.
        
        IMPORTANT NOTICE: This software and associated documentation files (the
        "Software") are proprietary and confidential products of Juntai Team (the
        "Licensor"). By accessing, copying, installing, or otherwise using this
        Software, you agree to be bound by the terms of this Agreement. If you do
        not agree to these terms, do not access or use the Software.
        
        1. OWNERSHIP
        
        The Software is owned by the Licensor and is protected by copyright laws
        and international copyright treaties, as well as other intellectual
        property laws and treaties. The Software is licensed, not sold. All rights
        not expressly granted herein are reserved by the Licensor.
        
        2. LICENSE GRANT
        
        Subject to the terms and conditions of this Agreement, the Licensor grants
        you a limited, non-exclusive, non-transferable, revocable license to use
        the Software solely for internal business purposes within your organization,
        and only to the extent authorized by a separate written agreement with the
        Licensor.
        
        3. RESTRICTIONS
        
        You shall NOT, and shall not permit any third party to:
        
          (a) copy, reproduce, distribute, sublicense, lease, rent, lend, or
              otherwise transfer the Software or any portion thereof to any
              third party;
        
          (b) modify, adapt, translate, reverse engineer, decompile, disassemble,
              or otherwise attempt to derive the source code of the Software,
              except to the extent expressly permitted by applicable law
              notwithstanding this limitation;
        
          (c) create derivative works based on the Software;
        
          (d) remove, alter, or obscure any proprietary notices, labels, or marks
              on the Software;
        
          (e) use the Software for any purpose other than as expressly permitted
              under this Agreement;
        
          (f) use the Software to develop a competing product or service;
        
          (g) publicly display, perform, or transmit the Software or any portion
              thereof;
        
          (h) make the Software available for external use, including but not
              limited to use as a service provider, time-sharing, or service
              bureau arrangement.
        
        4. CONFIDENTIALITY
        
        You acknowledge that the Software contains valuable trade secrets and
        confidential information of the Licensor. You agree to maintain the
        confidentiality of the Software and to use at least the same degree of
        care to prevent the unauthorized disclosure of the Software as you use to
        protect your own confidential information, but in no event less than
        reasonable care.
        
        5. NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
        OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE ENTIRE RISK AS
        TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
        
        6. LIMITATION OF LIABILITY
        
        IN NO EVENT SHALL THE LICENSOR BE LIABLE TO YOU OR ANY THIRD PARTY FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
        OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
        STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
        IN ANY WAY OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN
        IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        7. TERM AND TERMINATION
        
        This Agreement is effective until terminated. The Licensor may terminate
        this Agreement at any time if you fail to comply with any term of this
        Agreement. Upon termination, you must cease all use of the Software and
        destroy all copies, full or partial, of the Software.
        
        8. EXPORT COMPLIANCE
        
        You shall comply with all applicable export laws and regulations and
        shall not export, re-export, or transfer the Software in violation of
        any such laws or regulations.
        
        9. GOVERNING LAW
        
        This Agreement shall be governed by and construed in accordance with
        the laws of the People's Republic of China, without regard to its
        conflict of law principles.
        
        10. ENTIRE AGREEMENT
        
        This Agreement constitutes the entire agreement between the parties
        concerning the subject matter hereof and supersedes all prior and
        contemporaneous agreements and understandings, whether written or oral.
        
        For licensing inquiries, please contact: dev@juntai.com
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api<2.0.0,>=1.37.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.37.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.37.0
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.37.0
Description-Content-Type: text/markdown

# Juntai Observability Python

[简体中文](README_zh.md)

`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

```bash
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.

```python
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.

```python
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.

```python
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.

```python
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`](conventions/observability.v1.json). See
[`DEVELOPMENT.md`](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.
