agentscope-otel-langfuse
Langfuse OpenTelemetry tracing integration for AgentScope applications.
This package initializes an OpenTelemetry tracer provider, enables AgentScope's built-in LLM tracing, and adds Langfuse-compatible trace attributes for sessions, users, inputs, outputs, token usage, resource metadata, and Kubernetes metadata.
Features
- OTLP/HTTP trace export to an OpenTelemetry Collector or Langfuse-compatible endpoint.
- AgentScope
@trace_llmactivation when supported by the installed AgentScope version. - Request-level root traces with
trace_request(). - Langfuse session/user/input/output mapping.
- Token usage attributes using
gen_ai.usage.*. - Kubernetes metadata support via Downward API environment variables.
OTEL_RESOURCE_ATTRIBUTESsupport, mirrored into Langfuse trace metadata.- No-op behavior when tracing is disabled, so callers do not need telemetry conditionals.
Installation
pip install agentscope-otel-langfuse
For local development from this repository:
pip install -e ./agentscope-otel-langfuse
Quick Start
from agentscope_otel_langfuse import OTelConfig, init, trace_request
init(
OTelConfig.from_env(
service_name="my-agentscope-app",
)
)
with trace_request(
session_id="session-001",
user_id="user-001",
user_input="hello",
) as trace:
result = "world"
trace.set_output(result)
trace.set_usage({"input_tokens": 12, "output_tokens": 8})
Async usage:
async with trace_request(session_id=sid, user_id=uid, user_input=prompt) as trace:
response = await agent(messages)
trace.set_output(response)
trace.set_usage({"input_tokens": 100, "output_tokens": 50})
Configuration
Environment variables:
| Variable | Required | Description |
|---|---|---|
OTEL_ENABLED |
No | Set to true to enable tracing. Defaults to false. |
OTEL_EXPORTER_OTLP_ENDPOINT |
Yes, when enabled | OTLP HTTP endpoint. /v1/traces is appended automatically if omitted. |
OTEL_RESOURCE_ATTRIBUTES |
No | Comma-separated OTel resource attributes, for example deployment.environment=prod,service.version=1.2.3. |
Explicit values passed to OTelConfig.from_env() override environment variables:
config = OTelConfig.from_env(
service_name="payment-regulation-agent",
enabled=True,
endpoint="http://otel-collector:4318",
)
init(config)
Kubernetes Metadata
The SDK reads these optional environment variables and writes them as OTel resource attributes:
| Environment variable | OTel resource attribute |
|---|---|
K8S_POD_NAME |
k8s.pod.name |
K8S_POD_NAMESPACE |
k8s.namespace.name |
K8S_POD_UID |
k8s.pod.uid |
K8S_POD_IP |
k8s.pod.ip |
K8S_NODE_NAME |
k8s.node.name |
K8S_DEPLOYMENT_NAME |
k8s.deployment.name |
K8S_POD_LABEL_APP |
k8s.pod.label.app |
K8S_POD_LABEL_VERSION |
k8s.pod.label.version |
K8S_POD_LABEL_ENV |
k8s.pod.label.env |
Example Kubernetes env configuration:
env:
- name: OTEL_ENABLED
value: "true"
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://otel-collector:4318"
- name: K8S_POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: K8S_POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
- name: K8S_POD_UID
valueFrom:
fieldRef:
fieldPath: metadata.uid
- name: K8S_POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
- name: K8S_NODE_NAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: K8S_DEPLOYMENT_NAME
value: "payment-regulation-agent"
- name: OTEL_RESOURCE_ATTRIBUTES
value: "deployment.environment=prod,service.version=1.2.3"
Langfuse Metadata Mapping
Kubernetes and resource attributes are written twice:
- As OTel resource attributes, for backend/collector compatibility.
- As Langfuse metadata attributes on the root span, so they are visible in Langfuse trace metadata.
For example:
| Source attribute | Langfuse span attribute |
|---|---|
k8s.namespace.name=prod |
langfuse.trace.metadata.k8s_namespace_name=prod |
k8s.pod.name=agent-abc |
langfuse.trace.metadata.k8s_pod_name=agent-abc |
service.name=my-app |
langfuse.trace.metadata.service_name=my-app |
deployment.environment=prod |
langfuse.trace.metadata.deployment_environment=prod |
The same keys are also written under langfuse.observation.metadata.* for observation-level visibility.
API
OTelConfig
OTelConfig(enabled: bool, endpoint: str | None, service_name: str)
Use OTelConfig.from_env() to resolve environment variables and explicit overrides.
init(config)
Initializes OpenTelemetry tracing and activates AgentScope LLM tracing when available.
Returns a tracer object, or None when tracing is disabled or cannot be initialized.
trace_request(...)
Creates a sync/async context manager for a request-level root trace.
with trace_request(session_id=sid, user_id=uid, user_input=text) as trace:
trace.set_output(output)
trace.set_usage({"input_tokens": 1, "output_tokens": 2})
RequestTrace
Methods:
set_output(output)set_file_outputs(files)set_usage(usage)set_error()finish(error=False)
Troubleshooting
If traces do not appear:
- Confirm
OTEL_ENABLED=true. - Confirm
OTEL_EXPORTER_OTLP_ENDPOINTpoints to an OTLP HTTP traces endpoint or collector base URL. - Check application logs for
OTel tracer initialised. - Verify your collector exports to Langfuse correctly.
If Kubernetes attributes do not appear in Langfuse:
- Confirm the Kubernetes env vars are present in the running container.
- Confirm a request root span is created via
trace_request(). - Look for metadata keys such as
k8s_namespace_name,k8s_pod_name, anddeployment_environmentin Langfuse trace metadata.
Build and Publish
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
For TestPyPI:
python -m twine upload --repository testpypi dist/*
Metadata
Release files for agentscope-otel-langfuse 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentscope_otel_langfuse-0.1.1.tar.gz | 10.9 kB | Without provenance | Details for agentscope_otel_langfuse-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentscope_otel_langfuse-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agentscope_otel_langfuse-0.1.1-py3-none-any.whl |
Total release size: 20.6 kB
Release files / agentscope_otel_langfuse-0.1.1.tar.gz
| Download URL | agentscope_otel_langfuse-0.1.1.tar.gz |
|---|---|
| Size | 10.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7b222d9c14ffd57415977118f5f23804357b9bac1aa2a2c69c35d63fab002da4
|
|
BLAKE2b-256 checksum How to use checksums |
bd4ed32f5678f7da155e2711d5e48d40e3ddea379682ffc255c1cba1b4a4b64c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Release files / agentscope_otel_langfuse-0.1.1-py3-none-any.whl
| Download URL | agentscope_otel_langfuse-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3a896a36818cd9b3d91c011cdc8936e62d81a28e75200f1e642380481e896214
|
|
BLAKE2b-256 checksum How to use checksums |
1cf5a03a25f7013a06d535941713ae489ff6cb38f1e47cc307332a516bf51a63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Security for agentscope-otel-langfuse 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.