forge-observe

OpenTelemetry instrumentation for qwen-think reasoning sessions.

Emits traces and metrics for thinking budget consumption, mode switches, token splits, preserve_thinking utilization, and backend flag normalization. Works with any OTel-compatible backend (Jaeger, Grafana Tempo, Datadog, etc.).

Install

pip install forge-observe

# For OTLP export (Jaeger, Tempo, Datadog):
pip install forge-observe[otlp]

Quick start

Auto-instrumentation (recommended)

from forge_observe import instrument
instrument()

# Now use qwen-think as normal -- spans and metrics are emitted automatically.
from qwen_think import ThinkingSession
session = ThinkingSession(client=your_client)
response = session.chat("Implement a binary search tree")

Manual tracing

from forge_observe import ForgeTracer

tracer = ForgeTracer()
with tracer.session(attributes={"model": "Qwen3.6-35B"}) as span:
    with tracer.think_decision(mode="think", reason="coding task"):
        pass
    with tracer.budget_check(
        total_tokens=200000, used_tokens=50000,
        available_tokens=150000, action="ok",
    ):
        pass

Configuration

from forge_observe import configure, instrument

configure(
    service_name="my-app",
    otlp_endpoint="http://localhost:4317",
    otlp_protocol="grpc",
)
instrument()

All settings can be overridden via environment variables:

Variable Default Description
FORGE_OBSERVE_SERVICE_NAME forge-observe OTel service name
FORGE_OBSERVE_OTLP_ENDPOINT http://localhost:4317 OTLP collector endpoint
FORGE_OBSERVE_OTLP_PROTOCOL grpc grpc or http
FORGE_OBSERVE_ENABLED true Kill switch
FORGE_OBSERVE_CONSOLE_EXPORT false Print spans to stdout

What it instruments

Spans (auto-instrumented)

forge.session
  |-- forge.session.think_decision    router chose think/instruct, with reason
  |-- forge.session.param_swap        sampling params changed
  |-- forge.session.budget_check      budget evaluated, remaining tokens logged
  |-- forge.backend.normalize         flag normalization applied
  |-- forge.backend.response          response received, thinking/response split
  |-- forge.session.preserve_check    preserve_thinking reuse evaluated

Spans (manual via ForgeTracer)

forge.session.backend_call            wraps a backend API call (ForgeTracer.backend_call)
forge.mtp.config_decision             MTP config selected or disabled, with reason (ForgeTracer.mtp_config)

Metrics

Name Type Description
forge.session.budget_remaining Gauge Tokens remaining in budget
forge.session.thinking_tokens Counter Total thinking tokens emitted
forge.session.response_tokens Counter Total response tokens emitted
forge.session.mode_switches Counter Think/instruct mode flips
forge.session.preserve_reuse_rate Gauge Fraction of turns reusing prior thinking
forge.mtp.acceptance_rate Gauge Speculative token acceptance rate

Examples

See examples/ for setups targeting Jaeger, Grafana Tempo, and Datadog.

License

Apache-2.0

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 AD17 from gravatar.com AD17

Credits

Author: ArkaD171717

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.9

Provides Extra

dev otlp

Tags

llm metrics observability opentelemetry qwen qwen-think reasoning 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

forge_observe-0.1.2.tar.gz (18.5 kB view details)

Uploaded Source

Built Distribution

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

forge_observe-0.1.2-py3-none-any.whl (16.1 kB view details)

Uploaded Python 3

File details

Details for the file forge_observe-0.1.2.tar.gz.

File metadata

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

File hashes

Hashes for forge_observe-0.1.2.tar.gz
Algorithm Hash digest
SHA256 7a8869aeb95d1517c9a359b9f605c43050012a007040ae483e143e16155d10c1
MD5 fc13b5a048c39167379eddafccdc4450
BLAKE2b-256 899c2e02b34a5f60016c990ad9cbf387536c8797a48b76aca14b602f0d9bc6dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for forge_observe-0.1.2.tar.gz:

Publisher: publish.yml on ArkaD171717/FORGE-Observe

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

File details

Details for the file forge_observe-0.1.2-py3-none-any.whl.

File metadata

  • Download URL: forge_observe-0.1.2-py3-none-any.whl
  • Upload date:
  • Size: 16.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for forge_observe-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 520da20c13c2ba5452ade84275f413593efb34d4776837601e8fbe4cb4e1de3c
MD5 d965efcb7f73c56e298e135c315cc4b7
BLAKE2b-256 c0d27bd203bf7960e09172213e9938f331431c903f54c78bb51139ca837e3848

See more details on using hashes here.

Provenance

The following attestation bundles were made for forge_observe-0.1.2-py3-none-any.whl:

Publisher: publish.yml on ArkaD171717/FORGE-Observe

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.1.2 This release

2 files

0.1.1

2 files

0.1.0

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