Skip to content

v1.3.0 - Upstream alignment + cross-framework harmonization

Choose a tag to compare

View all tags
@Mandark-droid Mandark-droid released this 12 May 07:07
· 6 commits to main since this release
v1.3.0
e4c1a68

Highlights

This release realigns the library with the merged-or-pending upstream proposals at open-telemetry/semantic-conventions-genai (PRs #142, #143, #144), and adds cross-framework dual emission of three attributes the library already extracted in framework-specific form. Net effect: TraceVerde is now positioned as the reference implementation for three pending OTel standards proposals.

What's new

Cross-framework attribute harmonization

New canonical attribute Co-emitted alongside Coverage Upstream proposal
gen_ai.agent.name crewai.task.agent_role, autogen.agent.name, google_adk.agent.name, langchain.agent.name, openai.agent.name, pydantic_ai.agent.name, autogen_agentchat.agent.name 7 framework instrumentors, 9 emission sites semconv-genai#91
gen_ai.conversation.id session.id and framework-prefixed *.session.id / *.session_id 6 framework instrumentors + BaseInstrumentor.session_id_extractor (cross-cutting) semconv-genai#145
db.collection.name + db.vector.top_k vector.collection / vector.table / vector.limit / vector.n_results / vector.k (five backend-historical names collapse to one canonical pair) 5 vector DB backends (Qdrant, Chroma, Milvus, FAISS, LanceDB) semconv-genai#5

All harmonization is additive dual-emission — the existing backend/framework-prefixed names continue to be emitted unchanged for back-compat.

Multimodal canonical-JSON shape: aligned to PR #144's design pivot

Stripped media parts (instrumentation observed payload bytes but intentionally did not capture them — size cap exceeded, modality not allowed, redactor failure, etc.) no longer emit as a separate {"type": "stripped", ...} shape. They now keep the original part type (blob / uri / file) and modality, omit the content-bearing field, and set stripped_reason:

// before (v1.1.x – v1.2.x)
{ "type": "stripped", "modality": "image", "stripped_reason": "size_exceeded", "byte_size": 2000000 }

// after (v1.3.0+)
{ "type": "blob", "modality": "image", "mime_type": "image/png", "byte_size": 2000000, "stripped_reason": "size_exceeded" }

This matches the agreed shape in upstream PR #144 (under review): keep the part type so consumers can distinguish "no media in this turn" from "media was deliberately stripped" without inventing a new wire-format type.

  • Only visible when opt-in multimodal capture is enabled (GENAI_OTEL_MEDIA_CAPTURE_MODE=full or reference_only). Default text-only behaviour is unchanged.
  • The flat gen_ai.prompt.{n}.content.{m}.* attribute namespace is unchanged.

Upstream standards status

PR Proposal State
#142 document value on the Modality enum Approved, awaiting merge
#143 Optional byte_size on BlobPart/FilePart/UriPart Under review
#144 Optional content + stripped_reason on existing media parts, anyOf constraint requiring non-null payload or non-null stripped_reason Under review

The library's wire emission now conforms to the merged-or-proposed shape of all three.

Compatibility

  • API surface: no Python API changes. Library users see no breaking changes.
  • Wire format (text-only mode): unchanged.
  • Wire format (multimodal mode): the stripped-part change above. Anyone validating their consumer pipeline against the v1.1.x–v1.2.x {"type":"stripped"} shape will need a one-line update to also accept "type":"blob" (or "uri" / "file") with stripped_reason set instead. The flat gen_ai.media.stripped_reason attribute is unchanged.
  • Framework attribution: backwards-compatible. Framework-prefixed names continue to be emitted alongside the new gen_ai.* canonical names. Dashboards and queries that use the framework-prefixed names continue to work.

Tests

tests/media/ 52/52 · framework instrumentor tests 129/129 + 149/149 across the three harmonization PRs · tests/mcp_instrumentors/ 147/147. Pre-existing failures in test_mcp_instrumentor_integration and test_smolagents_instrumentor_integration (root cause: a litellm 1.x bug, not library code) are unchanged.

Full commit list

  • 4f51529 refactor: align library with upstream semconv-genai PRs #142/#143/#144 and harmonize gen_ai.agent.name
  • 1c38f90 refactor(mcp_instrumentors): harmonize vector DB top_k + collection.name across backends
  • fcf311a refactor: harmonize cross-framework conversation correlation as gen_ai.conversation.id
  • e4c1a68 chore: cut v1.3.0
Assets 2
Loading