feat(copaw): add CoPaw instrumentation, LoongSuite CI, and bootstrap mapping

.github/workflows/loongsuite_lint_0.yml

@@ -222,3 +222,22 @@ jobs:
       - name: Run tests
         run: tox -c tox-loongsuite.ini -e lint-loongsuite-instrumentation-crewai
 
+  lint-loongsuite-instrumentation-copaw:
+    name: LoongSuite loongsuite-instrumentation-copaw
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -c tox-loongsuite.ini -e lint-loongsuite-instrumentation-copaw
+

.github/workflows/loongsuite_test_0.yml

@@ -1533,3 +1533,79 @@ jobs:
       - name: Run tests
         run: tox -c tox-loongsuite.ini -e py313-test-loongsuite-instrumentation-crewai -- -ra
 
+  py310-test-loongsuite-instrumentation-copaw_ubuntu-latest:
+    name: LoongSuite loongsuite-instrumentation-copaw 3.10 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -c tox-loongsuite.ini -e py310-test-loongsuite-instrumentation-copaw -- -ra
+
+  py311-test-loongsuite-instrumentation-copaw_ubuntu-latest:
+    name: LoongSuite loongsuite-instrumentation-copaw 3.11 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -c tox-loongsuite.ini -e py311-test-loongsuite-instrumentation-copaw -- -ra
+
+  py312-test-loongsuite-instrumentation-copaw_ubuntu-latest:
+    name: LoongSuite loongsuite-instrumentation-copaw 3.12 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -c tox-loongsuite.ini -e py312-test-loongsuite-instrumentation-copaw -- -ra
+
+  py313-test-loongsuite-instrumentation-copaw_ubuntu-latest:
+    name: LoongSuite loongsuite-instrumentation-copaw 3.13 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -c tox-loongsuite.ini -e py313-test-loongsuite-instrumentation-copaw -- -ra
+

README-zh.md

@@ -33,6 +33,7 @@ LoongSuite Python Agent 同时也是上游 [OTel Python Agent](https://github.co
 | [AgentScope](https://github.com/agentscope-ai/agentscope) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-agentscope/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-agentscope/) |
 | [Agno](https://github.com/agno-agi/agno) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-agno/README.md) | in dev |
 | [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-claude-agent-sdk/) |
+| [CoPaw](https://github.com/agentscope-ai/CoPaw) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-copaw/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-copaw/) |
 | [CrewAI](https://github.com/crewAIInc/crewAI) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-crewai/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-crewai/) |
 | [DashScope](https://github.com/dashscope/dashscope-sdk-python) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-dashscope/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-dashscope/) |
 | [Dify](https://github.com/langgenius/dify) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-dify/README.md) | in dev |

README.md

@@ -33,6 +33,7 @@ Source tree: [`instrumentation-loongsuite/`](instrumentation-loongsuite).
 | [AgentScope](https://github.com/agentscope-ai/agentscope) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-agentscope/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-agentscope/) |
 | [Agno](https://github.com/agno-agi/agno) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-agno/README.md) | in dev |
 | [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-claude-agent-sdk/) |
+| [CoPaw](https://github.com/agentscope-ai/CoPaw) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-copaw/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-copaw/) |
 | [CrewAI](https://github.com/crewAIInc/crewAI) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-crewai/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-crewai/) |
 | [DashScope](https://github.com/dashscope/dashscope-sdk-python) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-dashscope/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-dashscope/) |
 | [Dify](https://github.com/langgenius/dify) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-dify/README.md) | in dev |
@@ -537,4 +538,4 @@ our [DingTalk group](https://qr.dingtalk.com/action/joingroup?code=v1,k1,mexukXI
 
 ## Resources
 * AgentScope: https://github.com/modelscope/agentscope
-* Observability Community: https://observability.cn
+* Observability Community: https://observability.cn

dev-requirements.txt

@@ -10,7 +10,7 @@ readme-renderer==42.0
 bleach==4.1.0 # transient dependency for readme-renderer
 markupsafe>=2.0.1
 codespell==2.1.0
-requests==2.32.3
+requests==2.32.4 # LoongSuite Extension: Copaw requires requests>=2.32.4
 ruamel.yaml==0.17.21
 flaky==3.7.0
 pre-commit==3.7.0; python_version >= '3.9'

instrumentation-loongsuite/README.md

@@ -4,9 +4,13 @@
 | [loongsuite-instrumentation-agentscope](./loongsuite-instrumentation-agentscope) | agentscope >= 1.0.0 | No | development
 | [loongsuite-instrumentation-agno](./loongsuite-instrumentation-agno) | agno | No | development
 | [loongsuite-instrumentation-claude-agent-sdk](./loongsuite-instrumentation-claude-agent-sdk) | claude-agent-sdk >= 0.1.0 | No | development
+| [loongsuite-instrumentation-copaw](./loongsuite-instrumentation-copaw) | copaw >= 0.1.0 | No | development
+| [loongsuite-instrumentation-crewai](./loongsuite-instrumentation-crewai) | crewai >= 0.80.0 | No | development
 | [loongsuite-instrumentation-dashscope](./loongsuite-instrumentation-dashscope) | dashscope >= 1.0.0 | No | development
 | [loongsuite-instrumentation-dify](./loongsuite-instrumentation-dify) | dify | No | development
 | [loongsuite-instrumentation-google-adk](./loongsuite-instrumentation-google-adk) | google-adk >= 0.1.0 | No | development
 | [loongsuite-instrumentation-langchain](./loongsuite-instrumentation-langchain) | langchain_core >= 0.1.0 | No | development
+| [loongsuite-instrumentation-langgraph](./loongsuite-instrumentation-langgraph) | langgraph >= 0.2 | No | development
+| [loongsuite-instrumentation-litellm](./loongsuite-instrumentation-litellm) | litellm >= 1.0.0 | No | development
 | [loongsuite-instrumentation-mcp](./loongsuite-instrumentation-mcp) | mcp >= 1.3.0, <= 1.25.0 | No | development
 | [loongsuite-instrumentation-mem0](./loongsuite-instrumentation-mem0) | mem0ai >= 1.0.0 | No | development

instrumentation-loongsuite/loongsuite-instrumentation-agentscope/tests/requirements.latest.txt

@@ -1,4 +1,39 @@
-# Test requirements for latest versions
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# ********************************
+# WARNING: NOT HERMETIC !!!!!!!!!!
+# ********************************
+#
+# This "requirements.txt" is installed in conjunction
+# with multiple other dependencies in the top-level "tox-loongsuite.ini"
+# file. In particular, please see:
+#
+#   agentscope-latest: {[testenv]test_deps}
+#   agentscope-latest: -r {toxinidir}/instrumentation-loongsuite/loongsuite-instrumentation-agentscope/tests/requirements.latest.txt
+#
+# This provides additional dependencies, namely:
+#
+#   opentelemetry-api
+#   opentelemetry-sdk
+#   opentelemetry-semantic-conventions
+#
+# ... with a "dev" version based on the latest distribution.
+
+# This variant of the requirements aims to test the system using
+# the newest supported version of external dependencies.
+
 agentscope>=1.0.0
 pytest
 pytest-asyncio

instrumentation-loongsuite/loongsuite-instrumentation-agentscope/tests/requirements.oldest.txt

@@ -1,4 +1,20 @@
-# Test requirements for latest versions
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This variant of the requirements aims to test the system using
+# the oldest supported version of external dependencies.
+
 agentscope>=1.0.0
 pytest
 pytest-asyncio

instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk/tests/requirements.latest.txt

@@ -12,6 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# ********************************
+# WARNING: NOT HERMETIC !!!!!!!!!!
+# ********************************
+#
+# This "requirements.txt" is installed in conjunction
+# with multiple other dependencies in the top-level "tox-loongsuite.ini"
+# file. In particular, please see:
+#
+#   claude-agent-sdk-latest: {[testenv]test_deps}
+#   claude-agent-sdk-latest: -r {toxinidir}/instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk/tests/requirements.latest.txt
+#
+# This provides additional dependencies, namely:
+#
+#   opentelemetry-api
+#   opentelemetry-sdk
+#   opentelemetry-semantic-conventions
+#
+# ... with a "dev" version based on the latest distribution.
+
 # This variant of the requirements aims to test the system using
 # the newest supported version of external dependencies.
 

instrumentation-loongsuite/loongsuite-instrumentation-copaw/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- **CoPaw instrumentation initialization**: ``CoPawInstrumentor`` registers
+  automatic instrumentation for CoPaw when ``instrument()`` is called (included
+  in LoongSuite distro automatic injection).
+  ([#162](https://github.com/alibaba/loongsuite-python-agent/pull/162))
+
+### Changed
+
+- Instrumentor depends on ``opentelemetry-util-genai`` and passes
+  ``tracer_provider``, ``meter_provider``, and ``logger_provider`` from
+  ``instrument()`` into the shared GenAI telemetry handler.
+  ([#162](https://github.com/alibaba/loongsuite-python-agent/pull/162))

instrumentation-loongsuite/loongsuite-instrumentation-copaw/README.md

@@ -0,0 +1,130 @@
+# LoongSuite CoPaw Instrumentation
+
+LoongSuite instrumentation for [CoPaw](https://github.com/agentscope-ai/CoPaw)
+(personal assistant built on AgentScope).
+
+## Getting Started
+
+CoPaw is started as its own app (CLI / process entrypoint), not as a library you
+embed with a few lines of `python your_script.py`. The practical approach is to
+install CoPaw, enable LoongSuite **Site-bootstrap** so instrumentation loads
+before CoPaw imports run, then start CoPaw with `copaw app`.
+
+### Step 1 — Install CoPaw
+
+```bash
+pip install copaw
+```
+
+### Step 2 — Site-bootstrap
+
+**Site-bootstrap** installs a **`.pth` hook** under `site-packages` so a small
+bootstrap module runs very early in the interpreter, before CoPaw’s imports.
+That path applies the same OpenTelemetry **auto-instrumentation** as
+`loongsuite-instrument` / `sitecustomize`, so you do **not** edit CoPaw source
+or wrap `copaw app` in a custom launcher. Installing `loongsuite-site-bootstrap`
+does **not** install instrumentations by itself; pair it with `loongsuite-bootstrap`
+(or equivalent `pip install` of the packages you need).
+
+**2.1 — Install `loongsuite-site-bootstrap`**
+
+```bash
+pip install loongsuite-site-bootstrap
+```
+
+**2.2 — Install instrumentations (including this package)**
+
+```bash
+pip install loongsuite-instrumentation-copaw loongsuite-instrumentation-agentscope
+```
+
+**2.3 — Enable the hook**
+
+In every shell or service manager that starts CoPaw, set:
+
+```bash
+export LOONGSUITE_PYTHON_SITE_BOOTSTRAP=True
+```
+
+The value is treated case-insensitively as on/off (`True` enables). You can also
+put `"LOONGSUITE_PYTHON_SITE_BOOTSTRAP": "true"` in `bootstrap-config.json`
+(see below); environment variables take **precedence** over the file for any key
+that is already set in the process.
+
+**2.4 — Configure export via `~/.loongsuite/bootstrap-config.json`**
+
+Create the directory and file if needed. The JSON root must be an object; string
+keys; values are applied to `os.environ` with **`setdefault`** semantics so
+**already-set environment variables are never overwritten** by the file.
+
+Example for **OTLP/gRPC** (adjust host, port, and service name):
+
+```json
+{
+  "OTEL_SERVICE_NAME": "copaw",
+  "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
+  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://127.0.0.1:4317",
+  "OTEL_TRACES_EXPORTER": "otlp",
+  "OTEL_METRICS_EXPORTER": "otlp"
+}
+```
+
+Example for quick local debugging with **console** exporters:
+
+```json
+{
+  "OTEL_SERVICE_NAME": "copaw",
+  "OTEL_TRACES_EXPORTER": "console",
+  "OTEL_METRICS_EXPORTER": "console"
+}
+```
+
+After a successful run you should see a line on stdout such as:
+`loongsuite-site-bootstrap: started successfully (OpenTelemetry auto-instrumentation initialized).`
+Do not start Python with `python -S` (that disables `site` and `.pth` processing).
+
+> **Beta / scope:** With the hook enabled, **every** Python process in that
+> environment that imports `site` may load the bootstrap—not only `copaw app`.
+> Use a dedicated virtual environment for production if you need isolation.
+
+### Step 3 — Run CoPaw
+
+With Site-bootstrap enabled in the same shell/session, start CoPaw as usual:
+
+```bash
+copaw app
+```
+
+Telemetry for `AgentRunner.query_handler` (Entry span) is then active without
+modifying CoPaw source code.
+
+### Optional: programmatic hook
+
+If you control an embedding process and prefer not to use site-bootstrap, you
+can call `CoPawInstrumentor().instrument()` (and `uninstrument()` when done)
+before CoPaw runs in that process—the hook point is still
+`AgentRunner.query_handler`. You must still configure the global
+`TracerProvider` / export (for example via OpenTelemetry env vars) consistently
+with the rest of your app.
+
+## What this package instruments
+
+When you enable LoongSuite for CoPaw, each user or channel “turn” that goes
+through CoPaw’s conversation runner produces **one application Entry trace** for
+that turn (span name `enter_ai_application_system`). It covers the full path on
+the CoPaw side—approval, built-in commands, or a normal agent run—not only the
+LLM call inside the agent.
+
+**Recorded on that span (when the data is available):**
+
+- **Operation**: entry into the AI application (`gen_ai.operation.name=enter`,
+  `gen_ai.span.kind=ENTRY`).
+- **Streaming**: time from the start of the turn to the first streamed chunk
+  (`gen_ai.response.time_to_first_token`, in nanoseconds).
+- **Identity / routing**: session id (`gen_ai.session.id`), user id
+  (`gen_ai.user.id`), CoPaw agent id (`copaw.agent_id`), channel
+  (`copaw.channel`).
+
+Calls to models, tools, and other AgentScope primitives are **not** duplicated
+here: use AgentScope (and your existing model client) instrumentations alongside
+this package so they appear as child spans under this entry when configured.