up

Author: lmolkova

.github/instructions/instrumentation-genai.instructions.md

@@ -6,16 +6,17 @@ Review rules for PRs touching `instrumentation-genai/**`. Flag violations with a
 
 ## 0. Reviewer mindset
 
-Review as long-term maintainer. For new instrumentations, consult upstream library docs and
-judge:
+Review as long-term maintainer.
+
+For new instrumentations, consult upstream library docs and judge:
 
 - Does the library already emit its own telemetry, making this instrumentation redundant?
 - Is the library used widely enough to warrant a package in this repo?
 - Does it avoid unbounded in-memory accumulation or other side-effects?
-- Does it raise errors that affect the user application at runtime?
+- Does the library raise exceptions that would reach user code through our wrapping?
 
-Prefer back-compat changes. Break users only for a real reason; prefer opt-in or additive.
-Breaking changes need explicit justification in the PR.
+For changes to existing instrumentations: prefer back-compat. Break users only for a real reason;
+prefer opt-in or additive. Breaking changes need explicit justification in the PR.
 
 ## 1. Scope of `instrumentation-genai/`
 
@@ -33,17 +34,18 @@ in `instrumentation/`, not here.
 - New instrumentations must add an entry under the correct folder in
   [`component_owners.yml`](../component_owners.yml) in the same PR. Contributor must commit to
   long-term maintenance. See
-  [Expectations from contributors](../../CONTRIBUTING.md#expectations-from-contributors) and
-  [Guideline for GenAI instrumentations](../../CONTRIBUTING.md#guideline-for-genai-instrumentations).
-- General [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations) still
-  applies.
+  [Expectations from contributors](../../CONTRIBUTING.md#expectations-from-contributors),
+  [Guideline for GenAI instrumentations](../../CONTRIBUTING.md#guideline-for-genai-instrumentations),
+  and the general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
 
 ## 3. Telemetry and configuration via `opentelemetry-util-genai`
 
-- Spans, logs, and metrics must go through `opentelemetry-util-genai`. Direct use of `Tracer`,
-  `Meter`, or `Logger` APIs is not allowed.
+- Spans, logs, metrics, and events must go through `opentelemetry-util-genai`. Direct use of
+  `Tracer`, `Meter`, `Logger`, or event APIs is not allowed.
 - Content capture, hooks, and other cross-cutting configuration are owned by the util.
   Instrumentations must not introduce their own env vars, settings, or hook interfaces.
+- Message content, prompts, and tool call arguments must only be set through the util's content
+  capture path — never as unconditional span/log attributes.
 - Adding attributes to invocations produced by the util is fine.
 - If a capability is missing in `opentelemetry-util-genai`, land it in the util first.
 
@@ -52,6 +54,13 @@ in `instrumentation/`, not here.
 - Attributes, spans, events, and metrics must match the
   [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai).
 - If a signal is not in semconv, wait until semconv lands.
+- Attribute names must come from the semconv attribute modules, not hardcoded strings:
+  - `gen_ai.*`: `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`
+  - `server.*`: `opentelemetry.semconv.attributes.server_attributes`
+  - `error.*`: `opentelemetry.semconv.attributes.error_attributes`
+  - other namespaces: corresponding module under `opentelemetry.semconv`
+- For attributes with a well-known value set in semconv, use the generated enum from the same
+  modules (e.g. `GenAiOutputTypeValues` for `gen_ai.output.type`) instead of string literals.
 
 ## 5. Exception handling
 
@@ -68,6 +77,7 @@ in `instrumentation/`, not here.
   exist.
 - Cover happy path and error scenarios, at minimum: provider error / endpoint unavailable, stream
   interrupted by network, stream closed early by the caller.
+- Tests must verify exact attribute names **and value types**, checked against the semconv spec.
 - Test against oldest and latest supported library versions via `tests/requirements.{oldest,latest}.txt`
   and `{oldest,latest}` `tox.ini` factors (see existing GenAI packages).
 

instrumentation-genai/AGENTS.md

@@ -39,6 +39,16 @@ Attributes, spans, events, and metrics follow the
 [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai).
 Do not emit signals that are not covered by semconv.
 
+Use the semconv attribute modules — do not hardcode attribute name strings:
+
+- `gen_ai.*` attributes: `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`
+- `server.*` attributes: `opentelemetry.semconv.attributes.server_attributes`
+- `error.*` attributes: `opentelemetry.semconv.attributes.error_attributes`
+- Other namespaces: use the corresponding module from `opentelemetry.semconv`
+
+For attributes with a well-known value set, use the generated enum from the same modules
+(e.g. `GenAiOutputTypeValues` for `gen_ai.output.type`) instead of string literals.
+
 ## 4. Tests
 
 - Use VCR cassettes for provider calls. Do not skip tests when an API key is missing.