Metadata-Version: 2.4
Name: juntai-usage
Version: 2.0.0
Summary: Canonical Juntai OpenTelemetry usage metrics producer
Author: Juntai Platform Team
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/zephytiju/JuntaiUsage
Project-URL: Documentation, https://github.com/zephytiju/JuntaiUsage#readme
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api<2,>=1.35

# Juntai Usage

`juntai-usage==2.0.0` is the metrics-only producer library for the approved
`juntai.usage/v0alpha1` semantic convention. It creates the exact Counter,
Histogram, and Gauge catalog through the application's host `MeterProvider`.
It does not configure an exporter or provide a collector, Usage endpoint,
database, KES credential, service runtime, or cost model.

```python
from asyncio import CancelledError

from juntai.usage import (
    ExpectedMeasurement,
    UsageContext,
    UsageLifecycle,
    UsageRecorder,
    UsageSource,
)

context = UsageContext(
    application_id="axiom",
    application_version="2026.9.2",
    pipeline_id="pipeline-3",
    workflow_id="workflow-3",
    execution_id="exec-42",
    attempt=1,
)
expected = (
    ExpectedMeasurement("juntai.usage.cpu.time", UsageSource.PROCESS),
)
window = UsageRecorder().start_window(context, expected=expected)
try:
    result = run_workload()
except CancelledError:
    window.close(UsageLifecycle.CANCELLED)
    raise
except Exception:
    window.close(UsageLifecycle.FAILED)
    raise
else:
    window.record("juntai.usage.cpu.time", cpu_seconds, source=UsageSource.PROCESS)
    window.close(UsageLifecycle.SUCCEEDED)
    return result
```

The application result remains authoritative. `close()` contains local SDK
recording failures and exposes them only through `WindowCloseResult`. An
unsupported or missing dimension is recorded with `window.unavailable()` and
never represented as numeric zero.

- [Metrics API](docs/metrics-api.md)
- [Migration from 1.x](docs/migration-from-1.x.md)
- Versioned fixtures ship in `juntai.usage/fixtures/v0alpha1`
- [Release history](CHANGELOG.md)

## Local gates

```bash
uv sync --dev
uv run ruff format --check .
uv run ruff check .
uv run pytest
uv run python -m build
```
