feat(llama-index): add loongsuite-instrumentation-llama-index (#18)

[RichardoMrMu]

What

Adds a new instrumentation package loongsuite-instrumentation-llama-index, providing automatic OpenTelemetry instrumentation for LlamaIndex (llama-index-core).

Closes #18 (roadmap #36 — "Add instrumentation for llama-index", contribution welcome).

How

Rather than monkey-patching call sites, this attaches to LlamaIndex's native instrumentation dispatcher (llama_index.core.instrumentation). LlamaIndex already emits a span/event stream through a root Dispatcher, assigning each instrumented call a span id_ and a parent_span_id that reflects the logical call tree (e.g. query → retrieve/synthesize, chat → complete). The package registers a BaseSpanHandler + BaseEventHandler on that dispatcher and re-projects the stream onto OpenTelemetry spans following the ARMS gen-ai semantic conventions, consuming parent_span_id directly so the OTel trace preserves LlamaIndex's own parent/child structure.

Span-kind mapping (gen_ai.span.kind): LLM / EMBEDDING / RETRIEVER / RERANKER / TASK (synthesis) / CHAIN (query engine) / AGENT (chat engine, agent run). Classification is method-first so class names embedding a misleading keyword (e.g. RetrieverQueryEngine.query) are classified correctly (CHAIN, not RETRIEVER). LLM/embedding events fold request model, messages and provider token usage onto the span. Content capture can be disabled with OTEL_INSTRUMENTATION_LLAMA_INDEX_CAPTURE_CONTENT=false.

Testing

tests/test_instrumentor.py drives the real llama-index-core dispatcher with in-process MockLLM / MockEmbedding and asserts on spans exported to an InMemorySpanExporter (no network, no credentials). Each GREEN assertion is paired with a RED baseline:

• RED: an LLM chat with no instrumentor active produces zero spans.
• GREEN: chat produces an LLM span with correct gen_ai.* attributes; chat→complete share one trace_id with complete nested under chat (proving parent_span_id mapping); embedding produces an EMBEDDING span.
• RED-after-teardown: after uninstrument(), a subsequent chat produces zero spans.
• Plus classification unit tests and idempotent-uninstrument.

15 tests pass (pytest), on llama-index-core 0.14.25 + opentelemetry-sdk.

Notes

• Package layout, pyproject.toml, entry point, CHANGELOG and bootstrap-registry entry follow the existing loongsuite-instrumentation-* conventions (e.g. terminus2).
• CHANGELOG.md updated (repo requirement).

[Copilot]

Copilot review overview

🟡 Changes recommended

Structured prediction classification, active-span teardown, hierarchy verification, and CI registration need correction.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 3 · 1

Open (4)

• Structured prediction methods are misclassified as CHAIN · New
• Uninstrumenting strands active spans and context tokens · New
• New package missing from tox-loongsuite configuration · New
• Test does not assert the exact parent span ID · New

What changed in this PR

Adds automatic OpenTelemetry instrumentation for LlamaIndex via its native dispatcher.

Changes:

• Maps LlamaIndex spans and events to GenAI telemetry.
• Adds lifecycle, hierarchy, classification, and embedding tests.
• Registers packaging and bootstrap metadata.

File	Description
pyproject.toml	Adds Ruff exceptions.
loongsuite-distro/​.../​loongsuite_instrumentation_llama_index.py	Adds bootstrap registry metadata.
.../​tests/​test_instrumentor.py	Tests spans and lifecycle.
.../​tests/​conftest.py	Configures test tracing.
.../​tests/​__init__.py	Initializes tests.
.../​test-requirements.txt	Adds test dependencies.
.../​version.py	Defines package version.
.../​package.py	Defines instrument dependency.
.../​llama_index/​__init__.py	Implements instrumentation.
.../​README.md	Documents usage.
.../​pyproject.toml	Defines package metadata.
.../​LICENSE	Adds Apache license.
.../​CHANGELOG.md	Records initial release.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.