Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
187 lines (135 loc) · 6.92 KB

CONTRIBUTING.md

File metadata and controls

187 lines (135 loc) · 6.92 KB
Raw

Contributing

Welcome to the OpenTelemetry Python GenAI Instrumentations repository!

New to OpenTelemetry? Read the New Contributor Guide first — it covers the CLA, Code of Conduct, and other prerequisites.

If you are using AI agents to assist with contributions, please also read AGENTS.md for guidance on how to use them responsibly in this project.

Prerequisites

  • Python — see tox.ini for the supported versions.
  • uv — used to manage the workspace and to back the tox test environments.

Code structure

├── instrumentation/
│   └── opentelemetry-instrumentation-genai-<name>/  # one package per GenAI library
│       ├── src/opentelemetry/instrumentation/genai/<name>/
│       ├── tests/
│       └── pyproject.toml
└── util/
    └── opentelemetry-util-genai/              # shared GenAI utilities
        ├── src/opentelemetry/util/genai/
        ├── tests/
        └── pyproject.toml

The monorepo uses uv workspaces; each package owns its own pyproject.toml, version, and entry points. tox.ini defines the test matrix.

Package naming and versioning

Instrumentation packages are named opentelemetry-instrumentation-genai-<name> and import as opentelemetry.instrumentation.genai.<name> — for example, opentelemetry-instrumentation-genai-anthropic imports opentelemetry.instrumentation.genai.anthropic.

Packages use the OpenTelemetry beta versioning format — MAJOR.MINORbN (e.g. 1.0b0). version.py carries a .dev suffix during development (1.0b0.dev); the release workflow drops it.

Making a change

1. Set up the environment

Install all packages and dev tools into a single workspace virtual environment:

uv sync --frozen --all-packages

2. Lint

uv run pre-commit run ruff --all-files

3. Test

Run the test environment for the package you changed (append -oldest or -latest for the version variants defined in tests/requirements.{oldest,latest}.txt):

uv run tox -e py312-test-instrumentation-genai-openai-latest

Run type checking across the workspace:

uv run tox -e typecheck

Managing cassettes (test recordings)

GenAI tests replay recorded HTTP interactions (cassettes) stored under each package's tests/cassettes/.

  • Run: nothing extra — cassettes replay automatically when present. Tests that need a cassette skip if it is missing and no real API key is set.
  • Record: delete the target tests/cassettes/<test_name>.yaml, export a real provider API key (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY), and rerun the test. pytest-vcr writes the cassette on the live call.
  • Sanitize: every package's vcr_config() in tests/conftest.py must scrub auth via filter_headers and strip identifying response headers via scrub_response_headers(...) from opentelemetry.test_util_genai.vcr. Diff each new cassette before committing — leaked API keys, org ids, or Set-Cookie values block the PR.
  • AI-generated cassettes: if you lack provider access, you may synthesize a cassette from the provider's API reference via AI. Add a # TODO: this is generated by AI, re-record comment at the top of the cassette, mention it in the PR, and open a follow-up issue to re-record it in CI against the real provider.
  • CI: replay-only; recording in CI is a future improvement.

4. Update the changelog

This repo uses towncrier to manage changelogs. Each PR with user-visible impact must add a changelog fragment under the affected package's .changelog/ directory rather than editing CHANGELOG.md directly.

Fragment path: <package>/.changelog/<PR_NUMBER>.<TYPE>

Types: added, changed, deprecated, removed, fixed.

The file contains a one-line description. For example, instrumentation/opentelemetry-instrumentation-genai-anthropic/.changelog/123.fixed:

fix request hook not being called when stream=True

Don't include the PR number in the body — towncrier appends it from the filename.

Preview the rendered changelogs locally:

uv run tox -e changelog-preview

If your change doesn't need an entry (pure docs/tooling), add the Skip Changelog label to the PR.

Skills

This repo ships skills (under .github/skills/) that automate the heavy, repeatable contribution flows. Trigger them deliberately when you start one of these tasks:

  • migrate-from-openinference — migrate an openinference-instrumentation-* package into this repo as an OTel GenAI package, or augment an existing package with the coverage OpenInference adds on top.
  • review-migration — review a ported or augmented package against its upstream implementation and write MIGRATION_REPORT.md.
  • write-conformance-tests — author conformance scenarios and the test_conformance.py runner for an instrumentation package.

Please contribute back anything you learn while using the skills that could help improve them!

Keep PRs small

One logical change per PR. Don't bundle unrelated fixes, refactors, or features — split them so each can be reviewed and reverted independently. Small, focused PRs are much easier to review, and therefore much more likely to land quickly.

If a PR review surfaces contentious or difficult points, consider splitting those into follow-up PRs so the uncontroversial parts can land and each of the harder points gets its own focused discussion and review.

Asking questions

Post in #otel-genai-instrumentation on CNCF Slack or join the next GenAI SIG meeting and add your topic to the meeting agenda. See the community repo for current meeting times.

Approvers and Maintainers

Maintainers

For more information about the maintainer role, see the community repository.

Approvers

For more information about the approver role, see the community repository.