loongsuite-python

June 12, 2026 · View on GitHub

English | 简体中文

介绍

LoongSuite Python Agent 是 LoongSuite（阿里巴巴统一可观测数据采集套件）的关键组件，为 Python 应用提供自动埋点（instrumentation）能力。

LoongSuite 包含以下核心组件：

LoongCollector：通用节点 Agent，基于 eBPF 提供日志采集、Prometheus 指标采集以及网络与安全采集能力。
LoongSuite Python Agent：为 Python 应用提供埋点能力的进程 Agent。
LoongSuite Go Agent：支持编译期埋点的 Golang 进程 Agent。
LoongSuite Java Agent：面向 Java 应用的进程 Agent。
其他语言 Agent 正在建设中。

LoongSuite Python Agent 同时也是上游 OTel Python Agent 的定制化发行版，增强了对主流 AI Agent 框架的支持。实现遵循最新的 GenAI 语义约定。

支持的框架与组件

LoongSuite instrumentation

源码目录：instrumentation-loongsuite/。

框架/组件	文档	发布
AgentScope	GUIDE	PyPI
Agno	GUIDE	in dev
Claude Agent SDK	GUIDE	PyPI
QwenPaw	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

发行版与辅助组件：

loongsuite-distro — https://pypi.org/project/loongsuite-distro/（包含 loongsuite-instrument、loongsuite-bootstrap）
loongsuite-otel-util-genai — https://pypi.org/project/loongsuite-otel-util-genai/
loongsuite-site-bootstrap— https://pypi.org/project/loongsuite-site-bootstrap/。

**包名迁移：**新的 LoongSuite GenAI 工具库发行包名为 loongsuite-otel-util-genai。旧的 loongsuite-util-genai 仍可供历史安装使用，但新的 LoongSuite GenAI 工具库更新会发布到新包名下。 Python 导入命名空间仍保持 opentelemetry.util.genai。

OpenTelemetry instrumentation — 生成式工作负载

源码目录：instrumentation-genai/。这些发行包遵循 OpenTelemetry 的生成式 AI语义约定（PyPI 包名为 opentelemetry-instrumentation-*）。

框架/组件	文档	发布
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

**说明：**在 LoongSuite 的发行方式下，请将这些包与 loongsuite-distro 以及 loongsuite-bootstrap / loongsuite-otel-util-genai 一起使用。避免将 loongsuite-otel-util-genai 与社区版 opentelemetry-util-genai 混装（见手动 pip 安装）。

OpenTelemetry instrumentation

源码目录：instrumentation/。这是通用应用与库的埋点集合；PyPI 项目名恒为 https://pypi.org/project/opentelemetry-instrumentation-<name>/。下表每一行都包含该 PyPI 链接及本仓库对应 README。

所有 instrumentation/ 包（点击展开）

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

快速开始

本示例使用 AgentScope。安装对应埋点后，其他技术栈也适用同样的 exporter 与 loongsuite-instrument 使用方式。

准备一个 Demo（AgentScope ReAct 示例）

可参考上游 ReAct agent 示例：你可以克隆 AgentScope，或按该目录中的 main.py 对齐。

步骤 1 — 安装 AgentScope

pip install agentscope

步骤 2 - 配置 DashScope

export DASHSCOPE_API_KEY={your_api_key}

将 {your_api_key} 替换为在 DashScope 控制台获取的有效密钥。

若需接入非 DashScope 的模型 API，请参考 AgentScope 文档：Model tutorial。

步骤 3 - 创建 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())

安装并运行 loongsuite

推荐集成方式：先安装 loongsuite-distro 及所需埋点（通过 loongsuite-bootstrap 或手动 pip），再使用 loongsuite-instrument 进行自动埋点。

步骤 1 — 安装 distro

pip install loongsuite-distro

可选：pip install loongsuite-distro[otlp] 以安装 OTLP 扩展（见 loongsuite-distro README）。

步骤 2 — 安装 instrumentations

使用 loongsuite-bootstrap（随 loongsuite-distro 提供）可从 GitHub Release tarball 安装 LoongSuite wheel，并从 PyPI 安装兼容版本的 opentelemetry-instrumentation-*。Bootstrap 采用两阶段安装：先安装 Release 中的 LoongSuite 制品，再安装固定版本 OpenTelemetry instrumentation（见 docs/loongsuite-release.md）。

以下方式三选一：

选项 A — 安装全部（来自某个 release）：

loongsuite-bootstrap -a install --latest
# 指定版本：loongsuite-bootstrap -a install --version X.Y.Z

选项 B — 自动探测（精简环境）：仅安装当前环境已有依赖对应的埋点：
```
loongsuite-bootstrap -a install --latest --auto-detect
```
选项 C — 手动 pip：按支持的框架与组件中的包名从 PyPI 自行安装。
```
pip install loongsuite-instrumentation-agentscope
```
说明：若你需要 instrumentation-genai/ 下的包，请优先采用 选项 A 或 B，并搭配 loongsuite-distro / loongsuite-bootstrap。仅手动 pip 安装时，若同时引入或以不同版本固定 loongsuite-otel-util-genai 与社区版 opentelemetry-util-genai，可能触发依赖解析冲突。

步骤 3 — 在 loongsuite-instrument 下运行

先通过环境变量和/或 loongsuite-instrument 参数配置遥测导出目标（见下文配置遥测导出），然后启动应用：

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

若需代码方式埋点、源码安装或 site-bootstrap（loongsuite-site-bootstrap），请见其他安装方式。

配置遥测导出

本地调试 — console

使用 SDK 的 console exporter，让 traces/metrics/logs 直接打印到终端，例如通过 loongsuite-instrument：

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

底层对应 ConsoleSpanExporter、ConsoleMetricExporter、ConsoleLogRecordExporter。

远端 / 生产 — OTLP

在应用启动前，需要安装 opentelemetry-exporter-otlp。

pip install opentelemetry-exporter-otlp

将 OpenTelemetry 指向支持 OTLP（gRPC 或 HTTP/protobuf）的后端，使用 OtlpSpanExporter、OtlpMetricExporter、OtlpLogExporter（或等价环境变量 / loongsuite-instrument 参数），例如：

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

另请参考 OpenTelemetry 环境变量说明（OTEL_EXPORTER_OTLP_*）。

其他安装方式

如果你不使用推荐的 loongsuite-instrument 集成方式，可选择下列一种方式。

代码方式埋点（Programmatic instrumentation）

适用于可修改应用代码、并希望显式控制 OpenTelemetry 初始化的场景。

步骤 1 — 自行安装 instrumentations

按支持的框架与组件中的名称从 PyPI 安装。

pip install loongsuite-instrumentation-agentscope

说明：若你需要 instrumentation-genai/ 下的包，请优先采用 选项 A 或 B，并搭配 loongsuite-distro / loongsuite-bootstrap。仅手动 pip 安装时，若同时引入或以不同版本固定 loongsuite-otel-util-genai 与社区版 opentelemetry-util-genai，可能触发依赖解析冲突。

步骤 2 — 在任何遥测产生前初始化 OpenTelemetry SDK

你需要接入与配置遥测导出一致的 exporter。

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])
)

步骤 3 — 调用框架 Instrumentor，然后直接启动应用。

from opentelemetry.instrumentation.agentscope import AgentScopeInstrumentor

AgentScopeInstrumentor().instrument()
# 然后再 import / 启动你的 agent（例如 asyncio.run(main())）

从源码安装（开发场景）

步骤 1 — 克隆仓库并切换分支

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

步骤 2 — 安装上游 OpenTelemetry Python core 与本地 LoongSuite 组件

从 opentelemetry-python 的 Git checkout 安装 core，并与本地可编辑包一次性安装，例如：

cd loongsuite-python
GIT_ROOT="git+https://github.com/open-telemetry/opentelemetry-python.git"
# 必须用一条 pip install：让 resolver 同时看到全部约束；
# 分步安装时，后续安装本地 editable 包可能触发 api/semconv 被降级或替换。
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

步骤 3 — 安装所需 instrumentation

例如：

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

步骤 4 — 在 loongsuite-instrument 下运行

先通过环境变量和/或 loongsuite-instrument 参数配置遥测导出目标（见下文配置遥测导出），然后启动应用：

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

Site-bootstrap（Beta）

无需修改业务代码，也无需额外 bootstrap 命令：通过 .pth hook 提前加载 LoongSuite distro（见 loongsuite-site-bootstrap/README.md）。

步骤 1 - 安装 LoongSuite Site Bootstrap

pip install loongsuite-site-bootstrap

步骤 2 — 安装 instrumentations

loongsuite-bootstrap -a install --latest
# 指定版本：loongsuite-bootstrap -a install --version X.Y.Z

若你希望使用其他安装方式，请参考安装并运行 loongsuite中的步骤 2 — 安装 instrumentations。

步骤 3 — 开启 hook

export LOONGSUITE_PYTHON_SITE_BOOTSTRAP=True
# 交互式 CLI / 应用可选：不要把通用成功提示写入 stdout。
export LOONGSUITE_PYTHON_SITE_BOOTSTRAP_LOG_SUCCESS=False
export LOONGSUITE_PYTHON_SITE_BOOTSTRAP_STATUS_FILE=/tmp/loongsuite-site-bootstrap-status.json

步骤 4 — 创建 ~/.loongsuite/bootstrap-config.json

写入你所需的 OpenTelemetry 环境变量键：

{
  "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"
}

然后执行 python demo.py。如需使用 console exporter、其他后端、改用 loongsuite-instrument（而非直接 python）、控制成功提示输出，或查看完整优先级/边界场景，请阅读 loongsuite-site-bootstrap/README.md。

**Beta：**Site-bootstrap 会影响其启用环境中的所有 Python 进程，生产环境使用前请先阅读包 README。

可选：OTLP 示例

AgentScope Studio

AgentScope Studio 提供 traces 与 metrics 的 Web UI。

pip install agentscope-studio
as_studio

使用 Studio 输出的 OTLP endpoint（通常是 http://127.0.0.1:31415），例如：

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

或者设置 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT。详情见 AgentScope Studio。

通过 LoongCollector 转发 OTLP 到 Jaeger

启动 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

启动 LoongCollector

按照其官方文档安装 LoongCollector。
在 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

启动 LoongCollector，例如：

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

让 Demo 通过 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

打开 Jaeger UI，确认能看到 traces。

Trace view in Jaeger

社区

欢迎你的反馈与建议。你可以加入我们的钉钉群，或扫描下方二维码与我们交流。

LoongCollector SIG	LoongSuite Python SIG

LoongCollector Go SIG	LoongSuite Java SIG

资源

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