Skip to content

Commit e98efc7

Browse files
MikeGoldsmithMikeGoldsmith
authored
Merge branch 'main' into log-handler-autoinstrumentation
2 parents 5f8c8b8 + cf0662d commit e98efc7

48 files changed

Lines changed: 1074 additions & 163 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
applyTo: "instrumentation-genai/**"
3+
---
4+
5+
Review rules for PRs touching `instrumentation-genai/**`. Flag violations with a link to the rule.
6+
7+
These rules are additive to
8+
[`instrumentation.instructions.md`](instrumentation.instructions.md), which applies to all
9+
instrumentation packages.
10+
11+
## 1. Scope of `instrumentation-genai/`
12+
13+
Only for:
14+
15+
- Generative AI inference providers,
16+
- Agentic frameworks,
17+
- Libraries directly supporting the above (e.g., MCP, GenAI protocols).
18+
19+
Database clients (including vector DBs used outside a GenAI-specific client) and CLI libs belong
20+
in `instrumentation/`, not here.
21+
22+
## 2. GenAI component ownership
23+
24+
See [`CONTRIBUTING.md#guideline-for-genai-instrumentations`](../../CONTRIBUTING.md#guideline-for-genai-instrumentations)
25+
for GenAI-specific maintenance expectations on top of the general
26+
[instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
27+
28+
## 3. Telemetry and configuration via `opentelemetry-util-genai`
29+
30+
- Spans, logs, metrics, and events must go through `opentelemetry-util-genai`. Direct use of
31+
`Tracer`, `Meter`, `Logger`, or event APIs is not allowed.
32+
- Content capture, hooks, and other cross-cutting configuration are owned by the util.
33+
Instrumentations must not introduce their own env vars, settings, or hook interfaces.
34+
- Message content, prompts, and tool call arguments must only be set through the util's content
35+
capture path — never as unconditional span/log attributes.
36+
- Adding attributes to invocations produced by the util is fine.
37+
- If a capability is missing in `opentelemetry-util-genai`, land it in the util first.
38+
39+
## 4. GenAI semantic conventions
40+
41+
- Attributes, spans, events, and metrics must match the
42+
[GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai).
43+
- `gen_ai.*` attribute names must come from
44+
`opentelemetry.semconv._incubating.attributes.gen_ai_attributes`.
45+
- For attributes with a well-known value set, use the generated enum from the same module
46+
(e.g. `GenAiOutputTypeValues` for `gen_ai.output.type`) instead of string literals.
47+
48+
## 5. Tests
49+
50+
- Use recorded VCR cassettes for provider calls. No live-key-only tests; skipping on missing key
51+
is not acceptable.
52+
- Cover streaming and non-streaming variants when both exist.
53+
- For error scenarios, at minimum include: provider error / endpoint unavailable, stream
54+
interrupted by network, stream closed early by the caller.
55+
56+
## 6. Examples
57+
58+
New instrumentations must ship a minimal example under the package's `examples/`, with both a
59+
`manual/` and a `zero-code/` (auto-instrumentation) variant.
60+
61+
## 7. PR description
62+
63+
- Cover which part of the GenAI semconv the change implements or follows (when applicable) and
64+
how instrumentations should consume it.
65+
66+
See also [AGENTS.md](../../AGENTS.md) for general repo rules.

‎.github/instructions/instrumentation.instructions.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
applyTo: "{instrumentation,instrumentation-genai}/**"
3+
---
4+
5+
Review rules for PRs touching `instrumentation/**` and `instrumentation-genai/**`. Flag violations
6+
with a link to the rule.
7+
8+
## 0. Reviewer mindset
9+
10+
Review as long-term maintainer.
11+
12+
For new instrumentations, consult upstream library docs and judge:
13+
14+
- Does the library already emit its own telemetry, making this instrumentation redundant?
15+
- Is the library used widely enough to warrant a package in this repo?
16+
- Does it avoid unbounded in-memory accumulation or other side-effects?
17+
18+
For changes to existing instrumentations: prefer back-compat. Break users only for a real reason;
19+
prefer opt-in or additive. Breaking changes need explicit justification in the PR.
20+
21+
## 1. Component ownership & maintenance commitment
22+
23+
- New instrumentations must add an entry under the correct folder in
24+
[`component_owners.yml`](../component_owners.yml) in the same PR. Contributor must commit to
25+
long-term maintenance. See
26+
[Expectations from contributors](../../CONTRIBUTING.md#expectations-from-contributors) and the
27+
general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
28+
29+
## 2. Semantic conventions
30+
31+
- Attribute names must come from the semconv attribute modules, not hardcoded strings. Use the
32+
module matching the namespace under `opentelemetry.semconv` (e.g. `server_attributes`,
33+
`error_attributes`, `http_attributes`, `db_attributes`, …).
34+
- For attributes with a well-known value set in semconv, use the generated enum from the same
35+
modules instead of string literals.
36+
- If a signal is not in semconv, wait until semconv lands.
37+
38+
## 3. Exception handling
39+
40+
- When catching exceptions from the underlying library to record telemetry, always re-raise the
41+
original exception unmodified.
42+
- Do not raise **new** exceptions in instrumentation/telemetry code.
43+
44+
## 4. Tests
45+
46+
- For every public API instrumented, cover sync/async variants when both exist.
47+
- Cover happy path and error scenarios.
48+
- Tests must verify exact attribute names **and value types**, checked against the semconv spec.
49+
- Test against oldest and latest supported library versions via `tests/requirements.{oldest,latest}.txt`
50+
and `{oldest,latest}` `tox.ini` factors.
51+
52+
See also [AGENTS.md](../../AGENTS.md) for general repo rules.

‎.github/instructions/util-genai.instructions.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
applyTo: "util/opentelemetry-util-genai/**"
3+
---
4+
5+
Review rules for PRs touching `util/opentelemetry-util-genai/**`. Flag violations with a link to
6+
the rule.
7+
8+
## 0. Reviewer mindset
9+
10+
Review as long-term maintainer. Every GenAI instrumentation in the repo depends on this package;
11+
churn breaks them. Default to back-compat changes. Every public addition is a long-term
12+
commitment — limit public API.
13+
14+
## 1. Semconv first
15+
16+
No code without semconv. If a signal, attribute, or operation is not in the
17+
[GenAI semconv](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/),
18+
land the semconv change first.
19+
20+
## 2. Semantic conventions
21+
22+
- Names (attributes, operations, spans) must match semconv exactly.
23+
- Use matching `opentelemetry.semconv` modules per namespace (`gen_ai`, `server`, `error`, …).
24+
Do not hardcode name strings if a constant exists.
25+
- Shared attributes must behave consistently across invocation types (same conditions, same
26+
defaults). If semconv marks an attribute for multiple invocations, set it on all.
27+
28+
## 3. API backwards compatibility
29+
30+
- Do not remove or rename public objects. Deprecate first via a docstring note pointing to the
31+
replacement (not `@deprecated` — unreliable).
32+
- Private modules and module-private objects start with `_`.
33+
- Default to internal (`_`-prefixed) unless instrumentations need it public.
34+
35+
## 4. Invocation shape
36+
37+
- `start_*()` factories must accept all sampling-relevant semconv attributes as parameters.
38+
Attributes also marked required by semconv must be required parameters (no default value).
39+
- `start_*()` factories must map 1:1 to distinct semconv operation types (inference, embeddings,
40+
tool execution, agent invocation, workflow invocation). Names must match the operation
41+
unambiguously — e.g., `create_agent` vs `invoke_agent` are distinct ops; `start_agent()` alone
42+
is ambiguous.
43+
- Each operation exposes both a factory (`start_inference(...)`) and a context-manager
44+
(`inference(...)`) form.
45+
- Never construct invocation types directly (`InferenceInvocation(...)`) — skips span creation,
46+
silent no-ops. Always use `handler.start_*()` or the context manager.
47+
48+
## 5. Exception handling
49+
50+
- When catching exceptions from the underlying library to record telemetry, always re-raise the
51+
original exception unmodified.
52+
- Do not raise **new** exceptions in utils code.
53+
54+
## 6. Performance
55+
56+
Keep the hot path tight:
57+
58+
- Avoid per-invocation allocations; do not accumulate state unboundedly.
59+
- Skip content capture when content capture is disabled.
60+
- Skip setting span attributes when the span is not recording.
61+
- Still record attributes that feed metrics — metric recording is independent of span sampling.
62+
63+
## 7. DRY
64+
65+
Do not copy-paste logic across invocation types. Extract shared helpers.
66+
67+
## 8. Tests
68+
69+
- Every new operation type or attribute change needs tests asserting exact attribute names **and
70+
value types**, checked against semconv.
71+
- Cover success (`invocation.stop()`), failure (`invocation.fail(exc)`), and conditional
72+
attribute logic.
73+
- Prefer public API in tests.
74+
75+
## 9. Documentation
76+
77+
- Docstrings for invocation types and span/event helpers must link to the corresponding semconv
78+
op.
79+
- When adding/changing attributes, update the docstring with what is set and when.
80+
81+
## 10. PR description
82+
83+
- Cover which part of the GenAI semconv the change implements or follows (when applicable) and
84+
how instrumentations should consume it.
85+
86+
See also [AGENTS.md](../../AGENTS.md) for general repo rules.

‎AGENTS.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,22 @@ Follow the PR scoping guidance in [CONTRIBUTING.md](CONTRIBUTING.md). Keep AI-as
1414
isolated to the requested change and never include unrelated cleanup or opportunistic improvements
1515
unless they are strictly necessary for correctness.
1616

17+
- One logical change per PR. Do not bundle multiple fixes, refactors, or features into the same
18+
PR - split them up so each can be reviewed and reverted independently.
19+
- Run the linter and the relevant tests locally and make sure they pass. See [Commands](#commands).
20+
1721
If you have been assigned an issue by the user or their prompt, please ensure that the
1822
implementation direction is agreed on with the maintainers first in the issue comments. If there are
1923
unknowns, discuss these on the issue before starting implementation. Do not forget that you cannot
20-
comment for users on issue threads on their behalf as it is against the rules of this project.
24+
comment for users on issue or pull request threads on their behalf as it is against the rules of this project.
25+
26+
## PR description
27+
28+
Follow the repo's [PR template](.github/pull_request_template.md) and fill applicable sections.
29+
Keep description short and focus on what is being changed and any gaps or concerns.
30+
31+
AI-generated analyses, long reports, or design dumps go in a relevant issue or a separate PR
32+
comment - not in the PR description.
2133

2234
## Structure
2335

@@ -55,6 +67,35 @@ uv run tox -e typecheck
5567
- 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.
5668
- Whenever applicable, all code changes should have tests that actually validate the changes.
5769

70+
## Instrumentation rules
71+
72+
Apply to packages under `instrumentation/` and `instrumentation-genai/`.
73+
74+
### Exception handling
75+
76+
- When catching exceptions from the underlying library to record telemetry, always re-raise the
77+
original exception unmodified.
78+
- Do not raise new exceptions in instrumentation/telemetry code.
79+
80+
### Semantic conventions
81+
82+
- Use the semconv attribute and metrics modules under `opentelemetry.semconv` — do not hardcode
83+
attribute or metric name strings.
84+
- For attributes with a well-known value set, use the generated enum from the same module instead
85+
of string literals.
86+
87+
### Tests
88+
89+
- For every public API instrumented, cover sync/async variants when both exist.
90+
- Cover happy path and error scenarios.
91+
- Tests must verify exact attribute names **and value types**, checked against the semconv spec.
92+
- Test against oldest and latest supported library versions via `tests/requirements.{oldest,latest}.txt`
93+
and `{oldest,latest}` `tox.ini` factors.
94+
95+
The parallel PR-review rules live in
96+
[`.github/instructions/instrumentation.instructions.md`](.github/instructions/instrumentation.instructions.md)
97+
and should be kept in sync with this section.
98+
5899
## Commit formatting
59100

60101
We appreciate it if users disclose the use of AI tools when the significant part of a commit is

‎CHANGELOG.md‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1515

1616
- Bump `pylint` to `4.0.5`
1717
([#4244](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4244))
18+
- `opentelemetry-instrumentation-sqlite3`: Add uninstrument, error status, suppress, and no-op tests
19+
([#4335](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4335))
20+
- Expand `AGENTS.md` with instrumentation/GenAI guidance and add PR review instructions.
21+
([#4457](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4457))
22+
23+
### Fixed
24+
25+
- `opentelemetry-instrumentation-pika` Use `ObjectProxy` instead of `BaseObjectProxy` for `ReadyMessagesDequeProxy` to restore iterability with wrapt 2.x
26+
([#4461](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4461))
27+
- `opentelemetry-instrumentation-dbapi` Use `ObjectProxy` instead of `BaseObjectProxy` for `TracedCursorProxy` to restore iterability with wrapt 2.x
28+
([#4427](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4427))
29+
- `opentelemetry-instrumentation-flask`: Clean up environ keys in `_teardown_request` to prevent duplicate execution
30+
([#4341](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4341))
31+
- `opentelemetry-instrumentation-flask`: Stop reading the deprecated (from 3.1) `flask.__version__` attribute; resolve the Flask version via `importlib.metadata`
32+
([#4422](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4422))
33+
- `opentelemetry-instrumentation-celery`: Coerce non-string values to strings in `CeleryGetter.get()` to prevent `TypeError` in `TraceState.from_header()` when Celery request attributes contain ints
34+
([#4360](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4360))
35+
- `opentelemetry-instrumentation-aiohttp-server`: Use `canonical` attribute of the `Resource` as a span name
36+
([#3896](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3896))
1837

1938
### Breaking changes
2039

@@ -1164,15 +1183,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
11641183

11651184
### Added
11661185

1167-
- Support `aio_pika` 9.x (([#1670](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1670])
1186+
- Support `aio_pika` 9.x ([#1670](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1670))
11681187
- `opentelemetry-instrumentation-redis` Add `sanitize_query` config option to allow query sanitization. ([#1572](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1572))
11691188
- `opentelemetry-instrumentation-elasticsearch` Add optional db.statement query sanitization.
11701189
([#1598](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1598))
11711190
- `opentelemetry-instrumentation-celery` Record exceptions as events on the span.
11721191
([#1573](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1573))
11731192
- Add metric instrumentation for urllib
11741193
([#1553](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1553))
1175-
- `opentelemetry/sdk/extension/aws` Implement [`aws.ecs.*`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md) and [`aws.logs.*`](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/cloud_provider/aws/logs/) resource attributes in the `AwsEcsResourceDetector` detector when the ECS Metadata v4 is available
1194+
- `opentelemetry/sdk/extension/aws` Implement [`aws.ecs.*`](https://opentelemetry.io/docs/specs/semconv/resource/cloud-provider/aws/ecs/) and [`aws.logs.*`](https://opentelemetry.io/docs/specs/semconv/resource/cloud-provider/aws/logs/) resource attributes in the `AwsEcsResourceDetector` detector when the ECS Metadata v4 is available
11761195
([#1212](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1212))
11771196
- `opentelemetry-instrumentation-aio-pika` Support `aio_pika` 8.x
11781197
([#1481](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1481))
@@ -1368,7 +1387,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
13681387
- Add a test for asgi using NoOpTracerProvider
13691388
([#1367](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/1367))
13701389

1371-
## [1.12.0rc2-0.32b0](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v1.12.0rc2-0.32b0) - 2022-07-01
1390+
## [1.12.0rc2-0.32b0](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v1.12.0rc2) - 2022-07-01
13721391

13731392
- Pyramid: Only categorize 500s server exceptions as errors
13741393
([#1037](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/1037))
@@ -2002,7 +2021,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
20022021
- `opentelemetry-instrumentation-grpc` Add tests for grpc span attributes, grpc `abort()` conditions
20032022
([#236](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/236))
20042023
- Add README and example app for Prometheus Remote Write Exporter
2005-
([#227](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/227]))
2024+
([#227](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/227))
20062025
- `opentelemetry-instrumentation-botocore` Adds a field to report the number of retries it take to complete an API call
20072026
([#275](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/275))
20082027
- `opentelemetry-instrumentation-requests` Use instanceof to check if responses are valid Response objects
@@ -2389,8 +2408,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
23892408
- `opentelemetry-ext-http-requests` Updates for core library changes
23902409

23912410
- `Added support for PyPy3` Initial release
2392-
2393-
## [#1033](https://github.com/open-telemetryopentelemetry-python-contrib/issues/1033)
2411+
([#1033](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/1033))
23942412

23952413
## Version 0.1a0 (2019-09-30)
23962414

0 commit comments

Comments
 (0)