Maple agent tracing: OpenTelemetry GenAI conventions (any language)

Goal: every conversation = one Maple Agent Session. Each user message = one trace rooted at an invoke_agent span, with a chat span per model call (model, tokens, transcript) and an execute_tool span per tool call (args, result, failures).

Mechanism: you write the spans. Maple classifies a span only by gen_ai.operation.name, groups a trace by gen_ai.conversation.id, and reads content only from span attributes. Hand-written spans show as framework "Unidentified" (vendor unknown:genai); that is expected.

Step 0: Detect

1. Language and entry points (web server, workers, scripts, serverless handlers).
2. Is a supported framework the real agent runtime? (@mastra/core, eve, ai, agents/@cloudflare/ai-chat, genkit/@genkit-ai/*, @openai/agents/openai-agents, langchain/langgraph, pydantic-ai, crewai, google-adk, llama-index, strands-agents, smolagents, agno, dspy, haystack-ai, agent-framework, Spring AI, litellm, Claude Agent SDK). If yes, stop and use maple-agent-tracing-<framework> instead; use this skill only for the parts that framework doesn't cover, or for the maple_ai.session.id wrapper (Step 4).
3. Existing OTel setup. Search for TracerProvider, NodeTracerProvider, NodeSDK, registerOTel, set_tracer_provider, opentelemetry-instrument, logfire.configure, sentry_sdk.init/Sentry.init, otel.SetTracerProvider. Exists → add Maple's exporter/processor to it; never create a second provider.
4. Existing GenAI auto-instrumentation on the model client (@opentelemetry/instrumentation-openai, opentelemetry-instrumentation-openai-v2, OpenLLMetry Traceloop.init, OpenInference OpenAIInstrumentor, logfire.instrument_openai). Pick one source of chat spans: either keep that instrumentation (then see maple-agent-tracing-provider-sdks) or remove it and write chat spans here. Both = every model call twice.
5. Find in the code: the agent loop (where one user message is handled), every model call site, every tool dispatch, sub-agent calls, and where the conversation/chat/thread id lives in the request.

Step 1: Key and region