Agent Trace SDK (agtrace)

Agent-aware tracing. Spans, events, and tool calls for LLM-driven workflows.

Why

Generic OpenTelemetry models web servers and database calls. AI agents need a different shape: prompts, tool calls, retries, fallbacks. agtrace borrows OTel's span tree but specializes the kind taxonomy so traces remain useful for debugging agents.

agtrace is the data primitive that apr-app and (eventually) sts-app will emit telemetry into — one trace per PR review, one span per LLM call, one span per tool invocation, all stitched together.

Status

v0.0.1 alpha. In-process tracer + JSONL exporter + CLI dump. OTLP / Jaeger / hosted-collector exporters land in v0.1+.

What v0.0.1 ships

  • agtrace.tracer.Tracer with a context-manager API.
  • Span kinds tuned for AI workloads: agent · prompt · tool_call · retry · fallback · unknown.
  • Automatic trace tree (parent / child via ContextVar — works under asyncio + threads).
  • Exception handling: an exception inside a span sets status="error" and records the exception type as an attribute. The exception still propagates.
  • Configurable exporter: default JSONL appender; in_memory_tracer() for tests; bring-your-own callable for OTLP / Sentry / Datadog.
  • CLI: agtrace dump --from-file traces.jsonl pretty-prints a trace tree.

Usage

from agtrace import default_tracer

tracer = default_tracer()      # writes to .agtrace/traces.jsonl

with tracer.span("agent.run", kind="agent", attributes={"agent": "pr-reviewer"}):
    with tracer.span("llm.call", kind="prompt") as s:
        s.set_attribute("model", "claude-sonnet-4-6")
        s.set_attribute("max_tokens", 1024)
        # ... call your LLM here ...
        s.add_event("rate-limited", attributes={"retry_after": "1.5"})

    with tracer.span("tool.call", kind="tool_call") as s:
        s.set_attribute("tool", "read_file")
        # ... run the tool ...

agtrace version
agtrace dump --from-file .agtrace/traces.jsonl
# Renders a Rich tree:
#   agent.run (agent)  (124ms)
#     agent=pr-reviewer
#     llm.call (prompt)  (98ms)
#       model=claude-sonnet-4-6
#     tool.call (tool_call)  (12ms)
#       tool=read_file

Roadmap

  • v0.1 — OtlpExporter (OTLP/HTTP) so traces ship into Honeycomb / Grafana / Datadog.
  • v0.1 — context propagation across HTTP boundaries (agtrace.propagation).
  • v0.2 — sampling + rate-limiting for production volume.
  • v0.3 — integration with tokencost so each prompt span carries the cost in its attributes natively.

Apache-2.0 license. See CHANGELOG.

Project links

Data verified by PyPI on May 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Abdullah_Bakir from gravatar.com Abdullah_Bakir

Credits

Author: Abdullah Bakir

GitHub Statistics

Data verified by PyPI on May 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Tags

agents developer-tools llm observability telemetry tracing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

devtrust_agtrace-0.0.2.tar.gz (11.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

devtrust_agtrace-0.0.2-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

File details

Details for the file devtrust_agtrace-0.0.2.tar.gz.

File metadata

  • Download URL: devtrust_agtrace-0.0.2.tar.gz
  • Upload date:
  • Size: 11.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for devtrust_agtrace-0.0.2.tar.gz
Algorithm Hash digest
SHA256 6ac931e228e4fb84cafad6b5b63b2202137c3d0982dfc1fe92cc4313c9ac8fd3
MD5 a07da36b2e41b07ebc9fc36ece244a05
BLAKE2b-256 181c86e09d9a43f7518ff3ad2df122dd27a5d43a6a97cf98b38a4582768ba0c1

See more details on using hashes here.

Provenance

The following attestation bundles were made for devtrust_agtrace-0.0.2.tar.gz:

Publisher: release.yml on AbdullahBakir97/DevTrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file devtrust_agtrace-0.0.2-py3-none-any.whl.

File metadata

File hashes

Hashes for devtrust_agtrace-0.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 6ee200e3a43ac0919c14f13742cbffd10ffa67e3a27691af204f0427d16e548d
MD5 66c6dca7e9512a65a34e82d2a47417af
BLAKE2b-256 e9f47918ff5816c279970699c76461381b916f8efcf8b145ad058f10ea1da0fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for devtrust_agtrace-0.0.2-py3-none-any.whl:

Publisher: release.yml on AbdullahBakir97/DevTrust

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.2 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page