Merge branch 'main' into add-baggage-log-processor

Author: lzchen

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Switch to SPDX license headers (#4533)
+# TODO: update with the squash-merge commit SHA after merge

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -8,8 +8,8 @@ body:
       value: |
         Thanks for taking the time to fill out this bug report! Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage and track down your bug as quickly as possible.
 
-        Before filing a bug, please be sure you have searched through [existing bugs](https://github.com/open-telemetry/opentelemetry-python-contrib/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug) to see if your bug is already addressed.  
-  
+        Before filing a bug, please be sure you have searched through [existing bugs](https://github.com/open-telemetry/opentelemetry-python-contrib/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug) to see if your bug is already addressed.
+
   - type: textarea
     id: environment
     attributes:
@@ -18,9 +18,9 @@ body:
         Please describe any aspect of your environment relevant to the problem, including your Python version, [platform](https://docs.python.org/3/library/platform.html), version numbers of installed dependencies, information about your cloud hosting provider, etc. If you're reporting a problem with a specific version of a library in this repo, please check whether the problem has been fixed on main.
       value: |
         OS: (e.g, Ubuntu)
-        Python version: (e.g., Python 3.9.10)
+        Python version: (e.g., Python 3.10.0)
         Package version: (e.g., 0.46.0)
-  
+
   - type: textarea
     attributes:
       label: What happened?

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

@@ -0,0 +1,66 @@
+---
+applyTo: "instrumentation-genai/**"
+---
+
+Review rules for PRs touching `instrumentation-genai/**`. Flag violations with a link to the rule.
+
+These rules are additive to
+[`instrumentation.instructions.md`](instrumentation.instructions.md), which applies to all
+instrumentation packages.
+
+## 1. Scope of `instrumentation-genai/`
+
+Only for:
+
+- Generative AI inference providers,
+- Agentic frameworks,
+- Libraries directly supporting the above (e.g., MCP, GenAI protocols).
+
+Database clients (including vector DBs used outside a GenAI-specific client) and CLI libs belong
+in `instrumentation/`, not here.
+
+## 2. GenAI component ownership
+
+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`
+
+- 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.
+
+## 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).
+- `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.
+
+## 5. Tests
+
+- Use recorded VCR cassettes for provider calls. No live-key-only tests; skipping on missing key
+  is not acceptable.
+- 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.
+
+## 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.
+
+## 7. PR description
+
+- Cover which part of the GenAI semconv the change implements or follows (when applicable) and
+  how instrumentations should consume it.
+
+See also [AGENTS.md](../../AGENTS.md) for general repo rules.

.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
+
+- 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.
+
+## 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.

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

@@ -0,0 +1,86 @@
+---
+applyTo: "util/opentelemetry-util-genai/**"
+---
+
+Review rules for PRs touching `util/opentelemetry-util-genai/**`. Flag violations with a link to
+the rule.
+
+## 0. Reviewer mindset
+
+Review as long-term maintainer. Every GenAI instrumentation in the repo depends on this package;
+churn breaks them. Default to back-compat changes. Every public addition is a long-term
+commitment — limit public API.
+
+## 1. Semconv first
+
+No code without semconv. If a signal, attribute, or operation is not in the
+[GenAI semconv](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/),
+land the semconv change first.
+
+## 2. Semantic conventions
+
+- Names (attributes, operations, spans) must match semconv exactly.
+- Use matching `opentelemetry.semconv` modules per namespace (`gen_ai`, `server`, `error`, …).
+  Do not hardcode name strings if a constant exists.
+- Shared attributes must behave consistently across invocation types (same conditions, same
+  defaults). If semconv marks an attribute for multiple invocations, set it on all.
+
+## 3. API backwards compatibility
+
+- Do not remove or rename public objects. Deprecate first via a docstring note pointing to the
+  replacement (not `@deprecated` — unreliable).
+- Private modules and module-private objects start with `_`.
+- Default to internal (`_`-prefixed) unless instrumentations need it public.
+
+## 4. Invocation shape
+
+- `start_*()` factories must accept all sampling-relevant semconv attributes as parameters.
+  Attributes also marked required by semconv must be required parameters (no default value).
+- `start_*()` factories must map 1:1 to distinct semconv operation types (inference, embeddings,
+  tool execution, agent invocation, workflow invocation). Names must match the operation
+  unambiguously — e.g., `create_agent` vs `invoke_agent` are distinct ops; `start_agent()` alone
+  is ambiguous.
+- Each operation exposes both a factory (`start_inference(...)`) and a context-manager
+  (`inference(...)`) form.
+- Never construct invocation types directly (`InferenceInvocation(...)`) — skips span creation,
+  silent no-ops. Always use `handler.start_*()` or the context manager.
+
+## 5. 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 utils code.
+
+## 6. Performance
+
+Keep the hot path tight:
+
+- Avoid per-invocation allocations; do not accumulate state unboundedly.
+- Skip content capture when content capture is disabled.
+- Skip setting span attributes when the span is not recording.
+- Still record attributes that feed metrics — metric recording is independent of span sampling.
+
+## 7. DRY
+
+Do not copy-paste logic across invocation types. Extract shared helpers.
+
+## 8. Tests
+
+- Every new operation type or attribute change needs tests asserting exact attribute names **and
+  value types**, checked against semconv.
+- Cover success (`invocation.stop()`), failure (`invocation.fail(exc)`), and conditional
+  attribute logic.
+- Prefer public API in tests.
+
+## 9. Documentation
+
+- Docstrings for invocation types and span/event helpers must link to the corresponding semconv
+  op.
+- When adding/changing attributes, update the docstring with what is set and when.
+
+## 10. PR description
+
+- Cover which part of the GenAI semconv the change implements or follows (when applicable) and
+  how instrumentations should consume it.
+
+See also [AGENTS.md](../../AGENTS.md) for general repo rules.

.github/labeler.yml

@@ -0,0 +1,6 @@
+gen-ai:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'instrumentation-genai/**'
+          - 'util/opentelemetry-util-genai/**'
+          - 'docs/instrumentation-genai/**'

.github/workflows/add-to-project.yml

@@ -0,0 +1,28 @@
+name: Add PR to project board
+
+on:
+  pull_request_target:
+    types: [opened, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  add-to-project:
+    name: add to project board
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      # NOTE: do NOT add an actions/checkout step here. This workflow uses
+      # pull_request_target (which has access to secrets) but must never
+      # execute code from the fork branch. See open-telemetry/opentelemetry-python#4955 for context.
+      - uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
+        id: otelbot-token
+        with:
+          app-id: ${{ vars.OTELBOT_PYTHON_APP_ID }}
+          private-key: ${{ secrets.OTELBOT_PYTHON_PRIVATE_KEY }}
+
+      - uses: actions/add-to-project@v1.0.2
+        with:
+          project-url: https://github.com/orgs/open-telemetry/projects/88
+          github-token: ${{ steps.otelbot-token.outputs.token }}

.github/workflows/check-links.yml

@@ -0,0 +1,84 @@
+name: check-links
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - '**/*.md'
+      - '**/*.rst'
+      - '.github/workflows/check-links.yml'
+      - '.github/workflows/check_links_config.json'
+  pull_request:
+    paths:
+      - '**/*.md'
+      - '**/*.rst'
+      - '.github/workflows/check-links.yml'
+      - '.github/workflows/check_links_config.json'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    if: ${{ github.actor != 'dependabot[bot]' && github.actor != 'otelbot[bot]' }}
+    timeout-minutes: 15
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Get changed markdown files
+        id: changed-files
+        uses: tj-actions/changed-files@v46
+        with:
+          files: |
+            **/*.md
+            **/*.rst
+
+      - name: Install markdown-link-check
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: npm install -g markdown-link-check@v3.12.2
+
+      - name: Check links on push to main
+        if: steps.changed-files.outputs.any_changed == 'true' && github.event_name == 'push'
+        run: |
+          markdown-link-check \
+            --verbose \
+            --config .github/workflows/check_links_config.json \
+            ${{ steps.changed-files.outputs.all_changed_files }} \
+            || { echo "Check that anchor links are lowercase"; exit 1; }
+
+      - name: Check new links only on pull requests
+        if: steps.changed-files.outputs.any_changed == 'true' && github.event_name == 'pull_request'
+        run: |
+          # Extract URLs only from added lines in the diff to avoid
+          # rate limiting when checking all links in large files like
+          # CHANGELOG.md. Only new/changed links are checked on PRs;
+          # pushes to main still check all links in changed files.
+          git diff "origin/${{ github.base_ref }}...HEAD" -- \
+            ${{ steps.changed-files.outputs.all_changed_files }} \
+            | grep '^+' | grep -v '^+++' \
+            | grep -oP 'https?://[^\s\)\]\"'"'"'`>]+' \
+            | sort -u > /tmp/new_links.txt
+
+          if [ ! -s /tmp/new_links.txt ]; then
+            echo "No new links found in diff, skipping check"
+            exit 0
+          fi
+
+          echo "Checking $(wc -l < /tmp/new_links.txt) new links:"
+          cat /tmp/new_links.txt
+
+          # Write links as markdown so markdown-link-check can parse them
+          awk '{print "- <" $0 ">"}' /tmp/new_links.txt > /tmp/new_links.md
+
+          markdown-link-check \
+            --verbose \
+            --config .github/workflows/check_links_config.json \
+            /tmp/new_links.md \
+            || { echo "Check that anchor links are lowercase"; exit 1; }

.github/workflows/check_links_config.json

@@ -0,0 +1,14 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "http(s)?://\\d+\\.\\d+\\.\\d+\\.\\d+"
+    },
+    {
+      "pattern": "http(s)?://localhost"
+    },
+    {
+      "pattern": "http(s)?://example.com"
+    }
+  ],
+  "aliveStatusCodes": [429, 200]
+}