expand beyond genai, create common files

Author: lmolkova

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

@@ -4,19 +4,9 @@ applyTo: "instrumentation-genai/**"
 
 Review rules for PRs touching `instrumentation-genai/**`. Flag violations with a link to the rule.
 
-## 0. Reviewer mindset
-
-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 the library raise exceptions that would reach user code through our wrapping?
-
-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.
+These rules are additive to
+[`instrumentation.instructions.md`](instrumentation.instructions.md), which applies to all
+instrumentation packages.
 
 ## 1. Scope of `instrumentation-genai/`
 
@@ -29,14 +19,11 @@ Only for:
 Database clients (including vector DBs used outside a GenAI-specific client) and CLI libs belong
 in `instrumentation/`, not here.
 
-## 2. Component ownership & maintenance commitment
+## 2. GenAI component ownership
 
-- 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),
-  [Guideline for GenAI instrumentations](../../CONTRIBUTING.md#guideline-for-genai-instrumentations),
-  and the general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
+See [`CONTRIBUTING.md#guideline-for-genai-instrumentations`](../../CONTRIBUTING.md#guideline-for-genai-instrumentations)
+for GenAI-specific maintenance expectations on top of the general
+[instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
 
 ## 3. Telemetry and configuration via `opentelemetry-util-genai`
 
@@ -49,44 +36,29 @@ in `instrumentation/`, not here.
 - 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.
 
-## 4. Semantic conventions
+## 4. GenAI semantic conventions
 
 - 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
-
-- No `raise` statements in instrumentation/telemetry code. Validation belongs in tests and
-  callers.
-- When catching library exceptions to record telemetry, re-raise the original exception
-  unmodified.
+- `gen_ai.*` attribute names must come from
+  `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`.
+- For attributes with a well-known value set, use the generated enum from the same module
+  (e.g. `GenAiOutputTypeValues` for `gen_ai.output.type`) instead of string literals.
 
-## 6. Tests
+## 5. Tests
 
 - Use recorded VCR cassettes for provider calls. No live-key-only tests; skipping on missing key
   is not acceptable.
-- For every public API touched, cover sync/async and streaming/non-streaming variants when both
-  exist.
-- Cover happy path and error scenarios, at minimum: provider error / endpoint unavailable, stream
+- Cover streaming and non-streaming variants when both exist.
+- For error scenarios, at minimum include: 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).
 
-## 7. Examples
+## 6. Examples
 
 New instrumentations must ship a minimal example under the package's `examples/`, with both a
 `manual/` and a `zero-code/` (auto-instrumentation) variant.
 
-## 8. PR description
+## 7. PR description
 
 - Cover which part of the GenAI semconv the change implements or follows (when applicable) and
   how instrumentations should consume it.

.github/instructions/instrumentation.instructions.md

@@ -0,0 +1,52 @@
+---
+applyTo: "{instrumentation,instrumentation-genai}/**"
+---
+
+Review rules for PRs touching `instrumentation/**` and `instrumentation-genai/**`. Flag violations
+with a link to the rule.
+
+## 0. Reviewer mindset
+
+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?
+
+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. Component ownership & maintenance commitment
+
+- 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 the
+  general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
+
+## 2. Semantic conventions
+
+- Attribute names must come from the semconv attribute modules, not hardcoded strings. Use the
+  module matching the namespace under `opentelemetry.semconv` (e.g. `server_attributes`,
+  `error_attributes`, `http_attributes`, `db_attributes`, …).
+- For attributes with a well-known value set in semconv, use the generated enum from the same
+  modules instead of string literals.
+- If a signal is not in semconv, wait until semconv lands.
+
+## 3. Exception handling
+
+- No new `raise` statements in instrumentation/telemetry code.
+- When catching library exceptions to record telemetry, re-raise the original exception
+  unmodified.
+
+## 4. Tests
+
+- For every public API instrumented, cover sync/async variants when both exist.
+- Cover happy path and error scenarios.
+- 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 also [AGENTS.md](../../AGENTS.md) for general repo rules.

AGENTS.md

@@ -14,10 +14,14 @@ Follow the PR scoping guidance in [CONTRIBUTING.md](CONTRIBUTING.md). Keep AI-as
 isolated to the requested change and never include unrelated cleanup or opportunistic improvements
 unless they are strictly necessary for correctness.
 
+- One logical change per PR. Do not bundle multiple fixes, refactors, or features into the same
+  PR - split them up so each can be reviewed and reverted independently.
+- Run the linter and the relevant tests locally and make sure they pass. See [Commands](#commands).
+
 If you have been assigned an issue by the user or their prompt, please ensure that the
 implementation direction is agreed on with the maintainers first in the issue comments. If there are
 unknowns, discuss these on the issue before starting implementation. Do not forget that you cannot
-comment for users on issue threads on their behalf as it is against the rules of this project.
+comment for users on issue or pull request threads on their behalf as it is against the rules of this project.
 
 ## PR description
 
@@ -63,6 +67,36 @@ uv run tox -e typecheck
 - Do not add `type: ignore` comments. If a type error arises, solve it properly or write a follow-up plan to address it in another PR.
 - Whenever applicable, all code changes should have tests that actually validate the changes.
 
+## Instrumentation rules
+
+Apply to packages under `instrumentation/` and `instrumentation-genai/`. See
+`instrumentation-genai/AGENTS.md` for additional GenAI-only rules.
+
+### Exception handling
+
+- When catching exceptions from the underlying library to record telemetry, always re-raise the
+  original exception unmodified.
+- Do not raise new exceptions in instrumentation/telemetry code.
+
+### Semantic conventions
+
+- Use the semconv attribute and metrics modules under `opentelemetry.semconv` — do not hardcode
+  attribute or metric name strings.
+- For attributes with a well-known value set, use the generated enum from the same module instead
+  of string literals.
+
+### Tests
+
+- For every public API instrumented, cover sync/async variants when both exist.
+- Cover happy path and error scenarios.
+- 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.
+
+The parallel PR-review rules live in
+[`.github/instructions/instrumentation.instructions.md`](.github/instructions/instrumentation.instructions.md)
+and should be kept in sync with this section.
+
 ## Commit formatting
 
 We appreciate it if users disclose the use of AI tools when the significant part of a commit is

instrumentation-genai/AGENTS.md

@@ -3,6 +3,9 @@
 Instrumentation packages here wrap specific libraries (OpenAI, Anthropic, etc.) and bridge
 them to the shared telemetry layer in `util/opentelemetry-util-genai`.
 
+These rules are additive to the shared instrumentation rules in the repo-root
+[AGENTS.md](../AGENTS.md).
+
 ## 1. Instrumentation Layer Boundary
 
 Do not call OpenTelemetry APIs (`tracer`, `meter`, `span`, event APIs) directly.
@@ -39,23 +42,15 @@ 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.
+`gen_ai.*` attribute names and the enums for well-known values (e.g. `GenAiOutputTypeValues` for
+`gen_ai.output.type`) live in `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`.
 
 ## 4. Tests
 
 - Use VCR cassettes for provider calls. Do not skip tests when an API key is missing.
-- For every public API touched, cover sync/async and streaming/non-streaming variants when
-  both exist.
-- Cover happy path and error scenarios, at minimum: provider error / endpoint unavailable,
-  stream interrupted by network, stream closed early by the caller.
+- Cover streaming and non-streaming variants when both exist.
+- Cover error scenarios, at minimum: provider error / endpoint unavailable, stream interrupted by
+  network, stream closed early by the caller.
 
 ## 5. Examples
 

util/opentelemetry-util-genai/AGENTS.md

@@ -69,10 +69,9 @@ propagation, so all telemetry calls become no-ops. Always use `handler.start_*()
 
 ## 3. Exception Handling
 
-- Do not add `raise {Error}` statements to `handler.py` or `types.py` — validation belongs in
-  tests and callers, not telemetry internals.
 - When catching exceptions from the underlying library to record telemetry, always re-raise
   the original exception unmodified.
+- Do not raise new exceptions in telemetry code.
 
 ## 4. Performance