loongsuite-python-agent

English | 简体中文

Introduction

Loongsuite Python Agent is a key component of LoongSuite, Alibaba's unified observability data collection suite, providing instrumentation for Python applications.

LoongSuite includes the following key components:

• LoongCollector: universal node agent, which prodivdes log collection, prometheus metric collection, and network and security collection capabilities based on eBPF.
• LoongSuite Python Agent: a process agent providing instrumentation for python applications.
• LoongSuite Go Agent: a process agent for golang with compile time instrumentation.
• LoongSuite Java Agent: a process agent for Java applications.
• Other upcoming language agent.

Loongsuite Python Agent is also a customized distribution of upstream OTel Python Agent, with enhanced support for popular AI agent framework. The implementation follows the latest GenAI semantic conventions.

Supported frameworks and components

LoongSuite instrumentation

Source tree: instrumentation-loongsuite/.

Framework/Components	Docs	Release
AgentScope	GUIDE	PyPI
Agno	GUIDE	in dev
Claude Agent SDK	GUIDE	PyPI
CrewAI	GUIDE	PyPI
DashScope	GUIDE	PyPI
Dify	GUIDE	in dev
Google ADK	GUIDE	PyPI
LangChain	GUIDE	PyPI
LangGraph	GUIDE	PyPI
LiteLLM	GUIDE	PyPI
MCP Python SDK	GUIDE	in dev
Mem0	GUIDE	PyPI

Distro and helpers:

• loongsuite-distro — https://pypi.org/project/loongsuite-distro/ (loongsuite-instrument, loongsuite-bootstrap)
• loongsuite-util-genai — https://pypi.org/project/loongsuite-util-genai/
• loongsuite-site-bootstrap — https://pypi.org/project/loongsuite-site-bootstrap/.

OpenTelemetry instrumentation — generative workloads

Source tree: instrumentation-genai/. These distributions follow OpenTelemetry generative semantic conventions (opentelemetry-instrumentation-* on PyPI).

Framework/Components	Docs	Release
Anthropic	GUIDE	PyPI
Claude Agent SDK	GUIDE	PyPI
Google GenAI	GUIDE	PyPI
LangChain	GUIDE	PyPI
OpenAI Agents	GUIDE	PyPI
OpenAI	GUIDE	PyPI
Vertex AI	GUIDE	PyPI
Weaviate	GUIDE	PyPI

Note: With LoongSuite’s distro, install these together with loongsuite-distro and loongsuite-bootstrap / loongsuite-util-genai. Avoid mixing loongsuite-util-genai with the community opentelemetry-util-genai (see manual pip installs).

OpenTelemetry instrumentation

Source tree: instrumentation/. General application and library instrumentations; PyPI project is always https://pypi.org/project/opentelemetry-instrumentation-<name>/. Each line below links to that URL and the package README in this repo.

All instrumentation/ packages (click to expand)

• opentelemetry-instrumentation-aio-pika — PyPI, readme
• opentelemetry-instrumentation-aiohttp-client — PyPI, readme
• opentelemetry-instrumentation-aiohttp-server — PyPI, readme
• opentelemetry-instrumentation-aiokafka — PyPI, readme
• opentelemetry-instrumentation-aiopg — PyPI, readme
• opentelemetry-instrumentation-asgi — PyPI, readme
• opentelemetry-instrumentation-asyncclick — PyPI, readme
• opentelemetry-instrumentation-asyncio — PyPI, readme
• opentelemetry-instrumentation-asyncpg — PyPI, readme
• opentelemetry-instrumentation-aws-lambda — PyPI, readme
• opentelemetry-instrumentation-boto — PyPI, readme
• opentelemetry-instrumentation-boto3sqs — PyPI, readme
• opentelemetry-instrumentation-botocore — PyPI, readme
• opentelemetry-instrumentation-cassandra — PyPI, readme
• opentelemetry-instrumentation-celery — PyPI, readme
• opentelemetry-instrumentation-click — PyPI, readme
• opentelemetry-instrumentation-confluent-kafka — PyPI, readme
• opentelemetry-instrumentation-dbapi — PyPI, readme
• opentelemetry-instrumentation-django — PyPI, readme
• opentelemetry-instrumentation-elasticsearch — PyPI, readme
• opentelemetry-instrumentation-falcon — PyPI, readme
• opentelemetry-instrumentation-fastapi — PyPI, readme
• opentelemetry-instrumentation-flask — PyPI, readme
• opentelemetry-instrumentation-grpc — PyPI, readme
• opentelemetry-instrumentation-httpx — PyPI, readme
• opentelemetry-instrumentation-jinja2 — PyPI, readme
• opentelemetry-instrumentation-kafka-python — PyPI, readme
• opentelemetry-instrumentation-logging — PyPI, readme
• opentelemetry-instrumentation-mysql — PyPI, readme
• opentelemetry-instrumentation-mysqlclient — PyPI, readme
• opentelemetry-instrumentation-pika — PyPI, readme
• opentelemetry-instrumentation-psycopg — PyPI, readme
• opentelemetry-instrumentation-psycopg2 — PyPI, readme
• opentelemetry-instrumentation-pymemcache — PyPI, readme
• opentelemetry-instrumentation-pymongo — PyPI, readme
• opentelemetry-instrumentation-pymssql — PyPI, readme
• opentelemetry-instrumentation-pymysql — PyPI, readme
• opentelemetry-instrumentation-pyramid — PyPI, readme
• opentelemetry-instrumentation-redis — PyPI, readme
• opentelemetry-instrumentation-remoulade — PyPI, readme
• opentelemetry-instrumentation-requests — PyPI, readme
• opentelemetry-instrumentation-sqlalchemy — PyPI, readme
• opentelemetry-instrumentation-sqlite3 — PyPI, readme
• opentelemetry-instrumentation-starlette — PyPI, readme
• opentelemetry-instrumentation-system-metrics — PyPI, readme
• opentelemetry-instrumentation-threading — PyPI, readme
• opentelemetry-instrumentation-tornado — PyPI, readme
• opentelemetry-instrumentation-tortoiseorm — PyPI, readme
• opentelemetry-instrumentation-urllib — PyPI, readme
• opentelemetry-instrumentation-urllib3 — PyPI, readme
• opentelemetry-instrumentation-wsgi — PyPI, readme

Quick start

This walkthrough uses AgentScope. The same exporter and loongsuite-instrument patterns apply to other stacks once their instrumentations are installed.

Prepare a demo (AgentScope ReAct example)

Use the upstream ReAct agent example as reference: you can clone AgentScope or align with that folder’s main.py.

Step 1 — Install AgentScope

pip install agentscope

Step 2 - Configure DashScope

export DASHSCOPE_API_KEY={your_api_key}

Replace {your_api_key} with a valid key from the DashScope console.

To connect to a different model API instead of DashScope, see the AgentScope documentation: Model tutorial.

Step 3 - Create ReAct Agent

# -*- coding: utf-8 -*-
"""The main entry point of the ReAct agent example."""
import asyncio
import os

from agentscope.agent import ReActAgent, UserAgent
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.model import DashScopeChatModel
from agentscope.tool import (
    Toolkit,
    execute_shell_command,
    execute_python_code,
    view_text_file,
)


async def main() -> None:
    """The main entry point for the ReAct agent example."""
    toolkit = Toolkit()

    toolkit.register_tool_function(execute_shell_command)
    toolkit.register_tool_function(execute_python_code)
    toolkit.register_tool_function(view_text_file)

    agent = ReActAgent(
        name="Friday",
        sys_prompt="You are a helpful assistant named Friday.",
        model=DashScopeChatModel(
            api_key=os.environ.get("DASHSCOPE_API_KEY"),
            model_name="qwen-max",
            enable_thinking=False,
            stream=True,
        ),
        formatter=DashScopeChatFormatter(),
        toolkit=toolkit,
        memory=InMemoryMemory(),
    )

    user = UserAgent("User")

    msg = None
    while True:
        msg = await user(msg)
        if msg.get_text_content() == "exit":
            break
        msg = await agent(msg)


asyncio.run(main())

Install and run loongsuite

Recommended integration approach: automatic instrumentation with loongsuite-instrument after installing loongsuite-distro and your instrumentations (via loongsuite-bootstrap or manual pip).

Step 1 — Install the distro

pip install loongsuite-distro

Optional: pip install loongsuite-distro[otlp] for OTLP extras (loongsuite-distro README).

Step 2 — Install instrumentations

Use loongsuite-bootstrap (shipped with loongsuite-distro) to install LoongSuite wheels from a GitHub Release tarball and compatible opentelemetry-instrumentation-* versions from PyPI. Bootstrap performs a two-phase install: LoongSuite artifacts from the release, then pinned OpenTelemetry instrumentation packages (see docs/loongsuite-release.md).

Pick one of the following:

• Option A — Install everything from a release:

  loongsuite-bootstrap -a install --latest
  # for specific version: loongsuite-bootstrap -a install --version X.Y.Z

• Option B — Auto-detect (lean environments): install only instrumentations for libraries already present:

  loongsuite-bootstrap -a install --latest --auto-detect

• Option C — Manual pip: install packages yourself from PyPI using the names in Supported frameworks and components.

  pip install loongsuite-instrumentation-agentscope

  Note: If you need packages under instrumentation-genai/, use Option A or B together with loongsuite-distro / loongsuite-bootstrap. Relying only on manual pip can cause dependency resolution conflicts when loongsuite-util-genai and the community opentelemetry-util-genai are both pulled in or pinned differently.

Step 3 — Run under loongsuite-instrument

Configure where telemetry is exported (see Configure telemetry export below) using environment variables and/or loongsuite-instrument flags, then start your app:

loongsuite-instrument \
  --traces_exporter console \
  --metrics_exporter console \
  --service_name demo \
  python demo.py

For programmatic instrumentation, install from source, or site-bootstrap (loongsuite-site-bootstrap), see Alternative installation methods.

Configure telemetry export

Local debugging — console

Use the SDK’s console exporters so traces/metrics/logs print to the terminal, for example via loongsuite-instrument:

loongsuite-instrument \
  --traces_exporter console \
  --metrics_exporter console \
  --logs_exporter console \
  python demo.py

Under the hood this aligns with ConsoleSpanExporter, ConsoleMetricExporter, and ConsoleLogRecordExporter.

Remote / production — OTLP

Before starting your application, install opentelemetry-exporter-otlp:

pip install opentelemetry-exporter-otlp

Point OpenTelemetry at a backend that accepts OTLP (gRPC or HTTP/protobuf), using OtlpSpanExporter, OtlpMetricExporter, OtlpLogExporter (or the equivalent env vars / loongsuite-instrument flags), for example:

export OTEL_SERVICE_NAME=demo
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317

loongsuite-instrument \
  --traces_exporter otlp \
  --metrics_exporter otlp \
  python demo.py

See also OpenTelemetry environment variables for OTEL_EXPORTER_OTLP_*.

Alternative installation methods

If you are not using the recommended loongsuite-instrument integration approach, use one of the options below.

Programmatic instrumentation

For applications where you can edit code and want explicit control over OpenTelemetry initialization.

Step 1 — Install instrumentations yourself from PyPI using the names in Supported frameworks and components.

pip install loongsuite-instrumentation-agentscope

Note: If you need packages under instrumentation-genai/, use Option A or B together with loongsuite-distro / loongsuite-bootstrap. Relying only on manual pip can cause dependency resolution conflicts when loongsuite-util-genai and the community opentelemetry-util-genai are both pulled in or pinned differently.

Step 2 — Initialize the OpenTelemetry SDK before anything emits telemetry. You are wiring the same exporters as in Configure telemetry export.

from opentelemetry import metrics, trace
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

resource = Resource.create({"service.name": "demo"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

metric_reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
metrics.set_meter_provider(
    MeterProvider(resource=resource, metric_readers=[metric_reader])
)

Step 3 — Call the framework instrumentor, then start your app without loongsuite-instrument.

from opentelemetry.instrumentation.agentscope import AgentScopeInstrumentor

AgentScopeInstrumentor().instrument()
# then import / start your agents (e.g. asyncio.run(main()))

Install from source (for development)

Step 1 — Clone this repository and checkout your branch.

git clone https://github.com/alibaba/loongsuite-python-agent.git

Step 2 — Install upstream OpenTelemetry Python core and local LoongSuite components from a Git checkout of opentelemetry-python:

cd loongsuite-python-agent
GIT_ROOT="git+https://github.com/open-telemetry/opentelemetry-python.git"
# Use ONE pip install command so resolver sees all constraints together;
# split installs can downgrade/replace api+semconv when local editable deps are installed later.
pip install \
  "${GIT_ROOT}#subdirectory=opentelemetry-api" \
  "${GIT_ROOT}#subdirectory=opentelemetry-semantic-conventions" \
  "${GIT_ROOT}#subdirectory=opentelemetry-sdk" \
  -e ./util/opentelemetry-util-genai \
  -e ./opentelemetry-instrumentation \
  -e ./loongsuite-distro

Step 3 — Install the instrumentations you need, for example:

pip install -e ./instrumentation-loongsuite/loongsuite-instrumentation-agentscope

Step 4 — Run under loongsuite-instrument

Configure where telemetry is exported (see Configure telemetry export below) using environment variables and/or loongsuite-instrument flags, then start your app:

loongsuite-instrument \
  --traces_exporter console \
  --metrics_exporter console \
  --service_name demo \
  python demo.py

Site-bootstrap (Beta)

Run without changing codes or bootstrap commands: a .pth hook loads LoongSuite’s distro early (see loongsuite-site-bootstrap/README.md).

Step 1 - Install LoongSuite Site Bootstrap

pip install loongsuite-site-bootstrap

Step 2 — Install instrumentations

loongsuite-bootstrap -a install --latest
# for specific version: loongsuite-bootstrap -a install --version X.Y.Z

If you want a different installation approach, see Step 2 — Install instrumentations in Install and run loongsuite.

Step 3 — Enable the hook:

export LOONGSUITE_PYTHON_SITE_BOOTSTRAP=True

Step 4 — Create ~/.loongsuite/bootstrap-config.json with the OpenTelemetry environments keys you need.

{
  "OTEL_SERVICE_NAME": "demo",
  "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://127.0.0.1:4317",
  "OTEL_TRACES_EXPORTER": "otlp",
  "OTEL_METRICS_EXPORTER": "otlp"
}

Then run python demo.py. For console exporters, other backends, using loongsuite-instrument instead of plain python, or full precedence / edge cases, see loongsuite-site-bootstrap/README.md.

Beta: Site-bootstrap affects every Python process in the environment where it is enabled; read the package README before using it in production.

---

Optional: OTLP examples

AgentScope Studio

AgentScope Studio provides a web UI for traces and metrics.

pip install agentscope-studio
as_studio

Use the OTLP endpoint Studio prints (often http://127.0.0.1:31415), for example:

loongsuite-instrument \
    --traces_exporter otlp \
    --metrics_exporter otlp \
    --exporter_otlp_protocol http/protobuf \
    --exporter_otlp_endpoint http://127.0.0.1:31415 \
    --service_name demo \
    python demo.py

Or set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT accordingly. Details: AgentScope Studio.

Forward OTLP to Jaeger via LoongCollector

Launch Jaeger

docker run --rm --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:1.53.0

Launch LoongCollector

1. Install LoongCollector per its documentation.
2. Add configuration under conf/continuous_pipeline_config/local/oltp.yaml:

enable: true
global:
  StructureType: v2
inputs:
  - Type: service_otlp
    Protocols:
      GRPC:
        Endpoint: 0.0.0.0:6666
flushers:
  - Type: flusher_otlp
    Traces:
      Endpoint: http://127.0.0.1:4317

3. Start LoongCollector, for example:

nohup ./loongcollector > stdout.log 2> stderr.log &

Run the demo against LoongCollector → Jaeger

loongsuite-instrument \
  --exporter_otlp_protocol grpc \
  --traces_exporter otlp \
  --exporter_otlp_insecure true \
  --exporter_otlp_endpoint 127.0.0.1:6666 \
  --service_name demo \
  python demo.py

Open the Jaeger UI and confirm traces arrive.

Community

We are looking forward to your feedback and suggestions. You can join our DingTalk group or scan the QR code below to engage with us.

LoongCollector SIG	LoongSuite Python SIG

LoongCollector Go SIG	LoongSuite Java SIG

Resources

• AgentScope: https://github.com/modelscope/agentscope
• Observability Community: https://observability.cn