Skip to main content

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_llm activation 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_ATTRIBUTES support, 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:

  1. Confirm OTEL_ENABLED=true.
  2. Confirm OTEL_EXPORTER_OTLP_ENDPOINT points to an OTLP HTTP traces endpoint or collector base URL.
  3. Check application logs for OTel tracer initialised.
  4. Verify your collector exports to Langfuse correctly.

If Kubernetes attributes do not appear in Langfuse:

  1. Confirm the Kubernetes env vars are present in the running container.
  2. Confirm a request root span is created via trace_request().
  3. Look for metadata keys such as k8s_namespace_name, k8s_pod_name, and deployment_environment in 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)

Source distribution for agentscope-otel-langfuse 0.1.1
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)

Table of built distributions (wheels) for agentscope-otel-langfuse 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page