Add Valkey Instrumentation by sightseeker · Pull Request #3478 · open-telemetry/opentelemetry-python-contrib

sightseeker · 2025-05-08T09:44:05Z

Description

This PR introduces a new Valkey instrumentation plugin for the OpenTelemetry Python Contrib library.
users can now automatically capture and export Valkey trace data alongside existing OpenTelemetry spans. This fills the gap for applications leveraging Valkey’s Client library, enabling end-to-end distributed tracing without manual span management.

Notes:

Since the valkey-search module is not yet GA, related tests are intentionally omitted in this PR.

Type of change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Added unit tests under instrumentation/opentelemetry-instrumentation-valkey/tests/ covering:
- automatic span creation on Valkey client calls
- context propagation across async boundaries
- correct attribute mapping (e.g. db.statement, db.valkey.args_length, db.valkey.database_index, net.peer.name)
Manual end-to-end test with example app instrumented via opentelemetry-instrumentation-valkey, verified spans in Jaeger backend
Test configuration:
- tox -e py38-test-instrumentation-valkey
- tox -e py39-test-instrumentation-valkey
- tox -e py310-test-instrumentation-valkey
- tox -e py311-test-instrumentation-valkey
- tox -e py312-test-instrumentation-valkey
- tox -e py313-test-instrumentation-valkey
- tox -e pypy3-test-instrumentation-valkey
Lint configuration:
- tox -e lint-instrumentation-valkey

Does This PR Require a Core Repo Change?

Yes. – Link to PR:
No.

Checklist:

Followed the style guidelines of this project
Changelogs have been updated (CHANGELOG.md entry under “New Features”)
Unit tests have been added
Documentation has been updated (README and Sphinx docs)

linux-foundation-easycla · 2025-05-08T09:44:10Z

The committers listed above are authorized under a signed CLA.

✅ login: sightseeker / name: Kohei Saito (0522e4e, 4db25d6, 4e1ffc7, 4f499ba, 4f9e1ad, 9a4656e, a4be038, f35ea5d, f9e86f4, fbdf10b, fe24656, 24ecc80, 2670aca, 3bef7a4, 4ac33b8, 4bbc332, 5fa3068, 6a1c5ef, 6f25fac, 866c219, 87633d2, a08cbb5, a45af90, abbc9cb, b5789a8, baf8d66, ea73a0e)

xrmx · 2025-05-08T10:45:50Z

 @retryable
 def check_redis_connection():
-    connection = redis.Redis(host=REDIS_HOST, port=REDIS_PORT)
+    connection = valkey.Redis(host=REDIS_HOST, port=REDIS_PORT)


we can test both no?

Thank you watching for this PR, sir
But, This is a draft of PR.
Could you waiting for ready.

@xrmx
Thank you for your patience. Would you mind taking a look and reviewing this PR?

this PR is so large that it is difficult to review. I suggest splitting it into several smaller PRs, as that would make more sense.

@zhengkezhou1

Thanks for the feedback! This instrumentation PR is actually a near-one-for-one copy of the existing Redis instrumentation, with only the service-specific bits renamed and a handful of Valkey-specific tweaks. To see how small the diff really is, you can run:

git diff --no-index instrumentation/opentelemetry-instrumentation-redis/src \ instrumentation/opentelemetry-instrumentation-valkey/src git diff --no-index instrumentation/opentelemetry-instrumentation-redis/tests/__init__.py \ instrumentation/opentelemetry-instrumentation-valkey/tests/__init__.py git diff --no-index instrumentation/opentelemetry-instrumentation-redis/tests/test_redis.py \ instrumentation/opentelemetry-instrumentation-valkey/tests/test_valkey.py git diff --no-index instrumentation/opentelemetry-instrumentation-redis/LICENCE \ instrumentation/opentelemetry-instrumentation-valkey/LICENCE git diff --no-index instrumentation/opentelemetry-instrumentation-redis/pyproject.toml \ instrumentation/opentelemetry-instrumentation-valkey/pyproject.toml git diff --no-index instrumentation/opentelemetry-instrumentation-redis/README.rst \ instrumentation/opentelemetry-instrumentation-valkey/README.rst git diff --no-index instrumentation/opentelemetry-instrumentation-redis/test-requirements.txt \ instrumentation/opentelemetry-instrumentation-valkey/test-requirements.txt git diff --no-index tests/opentelemetry-docker-tests/tests/redis/test_redis_functional.py \ tests/opentelemetry-docker-tests/tests/valkey/test_valkey_functional.py

Because the core of this PR is simply “copy + rename + small adjustments,” I think a single PR still keeps reviewable granularity. Please let me know if you’d prefer me to split out any particular piece!

amirreza-sf80 · 2025-06-04T19:26:34Z

adding valkey support was also discussed in valkey-io/valkey-py#190 (comment)

i'd be happy to see valkey supported here as well
but having two package with the exact same code base is gonna be problematic

one idea would be to create a base package that does the logic of both redis and valkey, and valkey and redis packages only implementing the parts needed for them
tho i can see this one has it's own problems as well

anyhow, if you need help on this i'm happy to lend a hand

There's no opentelemetry-instrumentation-valkey as of now, although it is WIP [1]. Fix the link for now, we can revert it later. [1] open-telemetry/opentelemetry-python-contrib#3478 Signed-off-by: Mikhail Koviazin <mikhail.koviazin@aiven.io>

sightseeker · 2026-03-11T07:43:23Z

Hi everyone, thank you for your patience and for all the thoughtful feedback!

I've merged the latest main to resolve conflicts and keep this PR up to date.

Regarding the suggestion from @amirreza-sf80 and @leandrodamascena about creating a shared base package for Redis and Valkey — I agree that maintaining two packages with nearly identical code is not ideal. I'm planning to refactor this by extracting the common instrumentation logic into a shared base that both Redis and Valkey can build on, with each package only implementing the backend-specific parts.

I'll be working on this in the coming updates. Any input or help is very welcome!

@pmeier Thanks for creating the external repo as a stopgap — that's really helpful for the community in the meantime.

@dcmcand Thanks for the support!

…ation Create opentelemetry-instrumentation-redis-valkey-base with KVStoreConfig dataclass and parameterized factory functions (_traced_execute_factory, _traced_execute_pipeline_factory, and async variants). Both Redis and Valkey instrumentation packages now delegate to this shared base, eliminating code duplication while preserving all existing behavior and backward compatibility. Valkey gains instrument_client/uninstrument_client and suppress_instrumentation support from following the Redis pattern through the shared base.

sightseeker · 2026-03-11T08:35:37Z

Hi everyone, the shared base package refactoring is now complete! Here's a summary of the changes:

Created opentelemetry-instrumentation-redis-valkey-base — a shared base package containing KVStoreConfig dataclass and parameterized factory functions for traced execution (sync/async, single command/pipeline)
Refactored opentelemetry-instrumentation-redis to delegate to the shared base (all 29 existing tests pass, no behavioral changes)
Refactored opentelemetry-instrumentation-valkey to use the shared base, gaining instrument_client()/uninstrument_client() and suppress_instrumentation support for free (12 tests pass)

This addresses the concerns raised by @amirreza-sf80 and @leandrodamascena about code duplication. The backend-specific differences are now isolated in each package's KVStoreConfig, while all common tracing logic lives in the shared base.

Ready for review — any feedback is welcome!

github-actions · 2026-03-26T04:07:06Z

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

tammy-baylis-swi · 2026-03-26T15:51:07Z

Hi @sightseeker thanks for this. Please could you merge main in and resolve merge conflicts? That will hopefully stop some of the ci/cd failures.

Then please also do tox -e precommit to fix the formatting

; Conflicts: ; .github/workflows/test_1.yml

sightseeker · 2026-04-01T02:17:58Z

@tammy-baylis-swi Done! I've merged main and resolved the conflicts, and ran tox -e precommit to fix formatting issues (unused imports and an RST title underline). Please take a look when you get a chance.

tammy-baylis-swi · 2026-04-01T23:33:52Z

+build-backend = "hatchling.build"
+
+[project]
+name = "opentelemetry-instrumentation-valkey"


Thanks @sightseeker !

Do you know who published this package with the same name?: https://pypi.org/project/opentelemetry-instrumentation-valkey/ We might have to name this something else.

Would you continue to own these new packages via https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/.github/component_owners.yml?

Good catch! I looked into it — the package on PyPI (opentelemetry-instrumentation-valkey by ajay-h1) appears to be a name-squatting package. Its description is "A professional-grade AI utility for automated data synchronization and backend management" with a homepage pointing to https://github.com/ai/library, which is completely unrelated to OpenTelemetry. I've reported it to PyPI as name-squatting on the official opentelemetry-instrumentation-* namespace.

Regarding component ownership — yes, I'm happy to be listed as the owner for the Valkey and redis-valkey-base packages in component_owners.yml. I'll add myself there.

Added myself as component owner for the Valkey and redis-valkey-base packages in 9a4656e.

Thank you that's awesome. Please keep us posted on the squatting report.

Thanks!

I reported it as malware, but PyPI responded that it doesn't appear to be malicious in nature. The proper process is a PEP 541 name transfer request via pypa/pypi-support. The package's homepage (https://github.com/ai/library) returns 404, so there's a strong case for the claim. It would likely carry more weight if filed by the open-telemetry organization.

Would someone from the maintainer team be able to help with that?

@sightseeker Filed a PEP 541 issue, you can follow pypi/support#10257

MikeGoldsmith · 2026-04-03T15:06:15Z

@@ -0,0 +1,472 @@
+# Copyright The OpenTelemetry Authors


Two semconv questions on this config:

db.system = "valkey" — "valkey" is not yet a recognised value in the OTel semantic conventions (neither in DbSystemValues nor the incubating db_attributes). Has a semconv issue or PR been filed to add it? Without one, Valkey spans will not match any official db.system filter in backends that expect known values.

db.valkey.database_index / db.valkey.args_length / db.valkey.pipeline_length — these are bespoke string literals with no semconv backing. Since Valkey is Redis-protocol-compatible, would it make sense to reuse DB_REDIS_DATABASE_INDEX for the index (at least until Valkey gets its own semconv definition)? Otherwise users may face a breaking change if/when semconv does define db.valkey.* attributes differently.

You're right, valkey is not yet a recognized value in the OTel semantic conventions. I checked and there's no existing issue or PR to add it. I'll file a semconv issue to propose adding valkey as a db.system value. In the meantime, since Valkey is a Redis fork with its own identity and roadmap, I think using valkey is the right direction — but happy to discuss.

That's a fair point. Since there's no semconv definition for Valkey yet, I think there are two options:

(a): Reuse Redis attributes (DB_REDIS_DATABASE_INDEX, etc.) for now and switch when semconv defines Valkey-specific ones

(b): Use db.valkey.* as proposed, accepting they may change later

I'd lean toward (a) for the db.valkey.* attributes — reusing DB_REDIS_DATABASE_INDEX etc. for now. For db.system, I still think "valkey" is correct since it identifies the actual database product being used.

Yeah, I think use the redis based attributes for now and switch to the keyval ones once approved makes sense.

I'm okay with using db.system=valkey for now too.

Thanks @sightseeker.

Done. switched to Redis-based attributes (DB_REDIS_DATABASE_INDEX, db.redis.args_length, db.redis.pipeline_length) in f35ea5d, keeping db.system="valkey".

; Conflicts: ; .github/workflows/test_1.yml ; CHANGELOG.md

MikeGoldsmith

Over all looks good. I've left a suggestion about not using net.transport and using db.system=keyval and reusing other Redis attributes pending specific ones being added to semconv.

Have you had any luck with getting the old package removed?

MikeGoldsmith · 2026-04-08T14:53:05Z

+from opentelemetry.semconv._incubating.attributes.net_attributes import (
+    NET_PEER_NAME,
+    NET_PEER_PORT,
+    NET_TRANSPORT,


net.transport has been deprecated, let's not introduce it.

Fix for review comment: a4be038

…finitions exist Use DB_REDIS_DATABASE_INDEX, db.redis.args_length, and db.redis.pipeline_length instead of bespoke db.valkey.* attributes. db.system remains "valkey" to identify the actual database product. Per review feedback from MikeGoldsmith.

Remove NET_TRANSPORT and NetTransportValues from the shared base util, as net.transport has been deprecated in OTel semantic conventions. Update Redis and Valkey tests accordingly. Per review feedback from MikeGoldsmith.

; Conflicts: ; .github/workflows/core_contrib_test.yml ; instrumentation/opentelemetry-instrumentation-redis/pyproject.toml ; opentelemetry-contrib-instrumentations/pyproject.toml

MikeGoldsmith

This looks good to me. Left one more suggestion of updating some semconv.

Still need to figure out the testing stuff and the Pypi pacakge ownership too.

…ER_NAME/NET_PEER_PORT Migrate from deprecated net.peer.name/net.peer.port to the newer server.address/server.port semconv attributes in the shared base package and both Redis/Valkey tests. Per review feedback from MikeGoldsmith.

copy redis codes to valkey instrumentation directory

87633d2

xrmx reviewed May 8, 2025

View reviewed changes

sightseeker added 6 commits May 8, 2025 21:40

modify libs to valkey from redis

4bbc332

remove version-compatibility checks in valkey instrumentation

baf8d66

undo accidental changes to test_redis_functiona.py

ea73a0e

fix valkey docker tests

6a1c5ef

fix for lint check of valkey inst and test code

4ac33b8

add github actions workflows for valkey

866c219

sightseeker force-pushed the feature/valkey branch from 669c7f8 to 73d1eca Compare May 9, 2025 06:05

fix imports order for ruff

24ecc80

sightseeker force-pushed the feature/valkey branch from 73d1eca to 24ecc80 Compare May 9, 2025 06:11

sightseeker added 3 commits May 9, 2025 15:24

fix for generate

b5789a8

update changelog for valkey instrumentation

a08cbb5

Merge branch 'main' into feature/valkey

a45af90

sightseeker marked this pull request as ready for review May 9, 2025 06:58

sightseeker requested a review from a team as a code owner May 9, 2025 06:58

sightseeker changed the title ~~Valkey Instrumentation from Redis Instrumentation Based~~ Add Valkey Instrumentation based from Redis Instrumentation May 10, 2025

Merge branch 'main' into feature/valkey

2670aca

sightseeker requested a review from xrmx May 10, 2025 05:30

sightseeker changed the title ~~Add Valkey Instrumentation based from Redis Instrumentation~~ Add Valkey Instrumentation May 12, 2025

sightseeker added 3 commits May 16, 2025 13:52

modify redis name to valkey in test_valkey.py

abbc9cb

Merge remote-tracking branch 'origin/feature/valkey' into feature/valkey

6f25fac

update development version to 0.55b0.dev

5fa3068

sightseeker requested review from zhengkezhou1 May 16, 2025 06:34

apply code format

3bef7a4

sightseeker mentioned this pull request Jun 4, 2025

Valkey Instrumentation #3568

Open

sightseeker force-pushed the feature/valkey branch from 73f1e72 to de7dd22 Compare March 11, 2026 08:29

github-actions Bot assigned lmolkova Mar 11, 2026

sightseeker added 3 commits March 11, 2026 17:32

Merge upstream/main into feature/valkey

f9e86f4

docs: add redis-valkey-base package entry to CHANGELOG

4f9e1ad

sightseeker force-pushed the feature/valkey branch from de7dd22 to 4f9e1ad Compare March 11, 2026 08:32

github-actions Bot removed the Stale label Mar 12, 2026

github-actions Bot added the Stale label Mar 26, 2026

tammy-baylis-swi removed the Stale label Mar 26, 2026

sightseeker added 2 commits April 1, 2026 09:21

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

fbdf10b

; Conflicts: ; .github/workflows/test_1.yml

fix: resolve precommit issues (unused imports, RST title underline)

0522e4e

tammy-baylis-swi reviewed Apr 1, 2026

View reviewed changes

MikeGoldsmith reviewed Apr 3, 2026

View reviewed changes

chore: add component ownership for valkey and redis-valkey-base packages

9a4656e

github-actions Bot assigned sightseeker Apr 4, 2026

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

fe24656

; Conflicts: ; .github/workflows/test_1.yml ; CHANGELOG.md

MikeGoldsmith reviewed Apr 8, 2026

View reviewed changes

MikeGoldsmith moved this from Ready for review to Approved PRs that need fixes in Python PR digest Apr 8, 2026

sightseeker added 3 commits April 15, 2026 10:02

refactor: remove deprecated net.transport from base package

a4be038

Remove NET_TRANSPORT and NetTransportValues from the shared base util, as net.transport has been deprecated in OTel semantic conventions. Update Redis and Valkey tests accordingly. Per review feedback from MikeGoldsmith.

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

4e1ffc7

; Conflicts: ; .github/workflows/core_contrib_test.yml ; instrumentation/opentelemetry-instrumentation-redis/pyproject.toml ; opentelemetry-contrib-instrumentations/pyproject.toml

MikeGoldsmith reviewed Apr 15, 2026

View reviewed changes

Comment thread ...ry-instrumentation-redis-valkey-base/src/opentelemetry/instrumentation/_redis_valkey/util.py Outdated

MikeGoldsmith mentioned this pull request Apr 15, 2026

fix(redis): extract ClusterPipeline commands from _execution_strategy in redis-py 6+ #4436

Open

2 tasks

xrmx mentioned this pull request Apr 16, 2026

PEP 541 Request: opentelemetry-instrumentation-valkey pypi/support#10257

Open

1 task

Conversation

sightseeker commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

linux-foundation-easycla Bot commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sightseeker May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amirreza-sf80 commented Jun 4, 2025

Uh oh!

sightseeker commented Mar 11, 2026

Uh oh!

sightseeker commented Mar 11, 2026

Uh oh!

github-actions Bot commented Mar 26, 2026

Uh oh!

tammy-baylis-swi commented Mar 26, 2026

Uh oh!

sightseeker commented Apr 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xrmx Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

sightseeker commented May 8, 2025 •

edited

Loading

linux-foundation-easycla Bot commented May 8, 2025 •

edited

Loading

sightseeker May 16, 2025 •

edited

Loading

xrmx Apr 16, 2026 •

edited

Loading