Add support for emitting inference events and enrich message types #3994

Cirilla-zmh · 2025-12-03T09:21:54Z

Description

Add support for emitting inference events.
Add gen_ai.system_instructions attributes for inference span or events.
Refactor span_utils.py for more brief implementation.
Add Reasoning, Blob, File, Uri message types.

Type of change

Please delete options that are not relevant.

New feature (non-breaking change which adds functionality)
This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

Add unit tests

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

Cirilla-zmh · 2025-12-03T09:51:44Z

Typecheck failure is not related to this PR, so it may be ignored. cc @aabmass

typecheck: commands[0]> pyright
/home/runner/work/opentelemetry-python-contrib/opentelemetry-python-contrib/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py
  /home/runner/work/opentelemetry-python-contrib/opentelemetry-python-contrib/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py:175:17 - error: No overloads for "join" match the provided arguments (reportCallIssue)
  /home/runner/work/opentelemetry-python-contrib/opentelemetry-python-contrib/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py:175:27 - error: Argument of type "Generator[str | Unknown | bytes | Any, None, None]" cannot be assigned to parameter "iterable" of type "Iterable[str]" in function "join"
    "Generator[str | Unknown | bytes | Any, None, None]" is not assignable to "Iterable[str]"
      Type parameter "_T_co@Iterable" is covariant, but "str | Unknown | bytes | Any" is not a subtype of "str"
        Type "str | Unknown | bytes | Any" is not assignable to type "str"
          "bytes" is not assignable to "str" (reportArgumentType)

Change-Id: I8fd0b896fc103a986f78c7351ce627611e545a62 Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: I5c4c93613e3e1084245b7298955a08cbc7c9708d Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: If34cfce0e7eb130db6a1e8e30a5f4be7c215285f Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: I847f75259e01729db88129a44b241afb0ea2aca4 Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: I818a042d275d3c8e3348647d73e34560e7d92f54 Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: I40b8e01bbe4fa9c182e99085a7c71d4536042247 Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: Ie07c495002143fb2f0cf88033206290eb85386ad Co-developed-by: Cursor <noreply@cursor.com>

DylanRussell · 2025-12-04T15:08:53Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

+
+    This function creates a LogRecord event following the semantic convention
+    for gen_ai.client.inference.operation.details as specified in the GenAI
+    event semantic conventions.


nit: can we link to the sem conv that defines this event

DylanRussell · 2025-12-04T15:09:48Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

+        ContentCapturingMode.EVENT_ONLY,
+        ContentCapturingMode.SPAN_AND_EVENT,
+    ):
+        return


this isn't right, this flag is for putting content attributes on the event, it shouldn't block the event being written altogether

@DylanRussell

You have a point, we might need an extra config flag to control inference event emission. But I have to ask: if the inference events don't log the chat history and just keep other attributes, how valuable are they really, since we already have inference spans?

IMO, recording the chat history is one of the main purposes of inference events.

today in Google AI instrumentations we always write the events.. They still have some value I think, that's why the flag was introduced not to just enable/disable the entire event, but just the sensitive content on the event..

DylanRussell · 2025-12-04T15:10:39Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

+    # Build event attributes by reusing the attribute getter functions
+    attributes: dict[str, Any] = {}
+    attributes.update(_get_llm_common_attributes(invocation))
+    attributes.update(_get_llm_request_attributes(invocation))
+    attributes.update(_get_llm_response_attributes(invocation))
+    attributes.update(
+        _get_llm_messages_attributes_for_event(
+            invocation.input_messages,


this could be one line I think ?

attributes.update(get_dict | get_dict | get_dict...)

DylanRussell · 2025-12-04T15:12:47Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py



-MessagePart = Union[Text, ToolCall, ToolCallResponse, Any]
+@dataclass()


is it possible to link to the sem convs where these types are defined ?

Please check https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb

Do you think if I should add links in the comments?

IMO yes, it'd be nice if we could link to an actual definition for each type. If they are just defined in that notebook I suppose 1 link is fine too

DylanRussell · 2025-12-04T15:14:13Z

util/opentelemetry-util-genai/tests/test_utils.py

+    from opentelemetry.sdk._logs.export import (
+        SimpleLogRecordProcessor,
+    )
+from opentelemetry.sdk._logs import LoggerProvider


should we bother with this or instead just update pyproject to require the latest version ?

JWinermaSplunk · 2025-12-04T19:23:15Z

I think changing some of the apply attributes methods to output a dictionary instead of attaching the attributes for events sake is ok, though making the methods llm specific will lead to a lot of overlapping code overtime if more genai types are implemented in the future. More so applies to methods like _apply_common_span_attributes, _apply_finish_attributes, etc, which could take different genai type invocations.

Cirilla-zmh · 2025-12-05T05:52:49Z

More so applies to methods like _apply_common_span_attributes, _apply_finish_attributes, etc, which could take different genai type invocations.

@JWinermaSplunk Thanks for your suggestions! We do need to classify the attributes for common, inference, agent and so on to reuse them as much as possible. However, I don't want to involve many features in this PR because that means we'd better refactor the design of LLMInovcation to a layered model with CommonInvocation, MessagesInocation and so on.

Could you please create another issue to mark this proposal? I believe @keith-decker and @aabmass would also be interested in this.

Cirilla-zmh requested a review from a team as a code owner December 3, 2025 09:21

github-actions bot assigned DylanRussell Dec 3, 2025

Cirilla-zmh added 5 commits December 4, 2025 13:37

Add support for emitting inference events and enrich message types

eebf58e

Change-Id: I8fd0b896fc103a986f78c7351ce627611e545a62 Co-developed-by: Cursor <noreply@cursor.com>

Add change log

cd4b29d

Change-Id: I5c4c93613e3e1084245b7298955a08cbc7c9708d Co-developed-by: Cursor <noreply@cursor.com>

Fix unit tests

b342978

Change-Id: If34cfce0e7eb130db6a1e8e30a5f4be7c215285f Co-developed-by: Cursor <noreply@cursor.com>

Fix linting failure

7f7b3cf

Change-Id: I847f75259e01729db88129a44b241afb0ea2aca4 Co-developed-by: Cursor <noreply@cursor.com>

Fix readme

1d312c5

Change-Id: I818a042d275d3c8e3348647d73e34560e7d92f54 Co-developed-by: Cursor <noreply@cursor.com>

Cirilla-zmh force-pushed the minghui/log_chat_messages branch from fbce5a2 to 1d312c5 Compare December 4, 2025 05:37

Cirilla-zmh added 2 commits December 4, 2025 13:55

Format codes

d32ec3e

Change-Id: I40b8e01bbe4fa9c182e99085a7c71d4536042247 Co-developed-by: Cursor <noreply@cursor.com>

Fix missing trace context in events

e0d35b2

Change-Id: Ie07c495002143fb2f0cf88033206290eb85386ad Co-developed-by: Cursor <noreply@cursor.com>

DylanRussell reviewed Dec 4, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support for emitting inference events and enrich message types #3994

Add support for emitting inference events and enrich message types #3994

Cirilla-zmh commented Dec 3, 2025 •

edited

Loading

Uh oh!

Cirilla-zmh commented Dec 3, 2025 •

edited

Loading

Uh oh!

DylanRussell Dec 4, 2025

Uh oh!

DylanRussell Dec 4, 2025

Uh oh!

Cirilla-zmh Dec 5, 2025 •

edited

Loading

Uh oh!

DylanRussell Dec 5, 2025 •

edited

Loading

Uh oh!

DylanRussell Dec 4, 2025

Uh oh!

DylanRussell Dec 4, 2025

Uh oh!

Cirilla-zmh Dec 5, 2025

Uh oh!

DylanRussell Dec 5, 2025

Uh oh!

DylanRussell Dec 4, 2025

Uh oh!

JWinermaSplunk commented Dec 4, 2025

Uh oh!

Cirilla-zmh commented Dec 5, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants



		MessagePart = Union[Text, ToolCall, ToolCallResponse, Any]
		@dataclass()

Add support for emitting inference events and enrich message types #3994

Are you sure you want to change the base?

Add support for emitting inference events and enrich message types #3994

Conversation

Cirilla-zmh commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Cirilla-zmh commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DylanRussell Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

DylanRussell Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Cirilla-zmh Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DylanRussell Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DylanRussell Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

DylanRussell Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Cirilla-zmh Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

DylanRussell Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

DylanRussell Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

JWinermaSplunk commented Dec 4, 2025

Uh oh!

Cirilla-zmh commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Cirilla-zmh commented Dec 3, 2025 •

edited

Loading

Cirilla-zmh commented Dec 3, 2025 •

edited

Loading

Cirilla-zmh Dec 5, 2025 •

edited

Loading

DylanRussell Dec 5, 2025 •

edited

Loading

Cirilla-zmh commented Dec 5, 2025 •

edited

Loading