Merge remote-tracking branch 'upstream/main' into feature/valkey

; Conflicts:
;	CHANGELOG.md

Author: sightseeker

.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/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]
+}

.github/workflows/labeler.yml

@@ -0,0 +1,18 @@
+name: PR Labeler
+
+on:
+  pull_request_target:
+
+permissions:
+  contents: read
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/labeler@v6
+        with:
+          sync-labels: false

.github/workflows/lint.yml

@@ -1371,3 +1371,22 @@ jobs:
 
       - name: Run tests
         run: tox -e lint-opamp-client
+
+  lint-license-header-check:
+    name: license-header-check
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e lint-license-header-check