[vishal-bala]

Motivation

The metrics in the PR below show how SemanticCache performs overall. To explain a single slow or missed lookup, you need to see where it spent its time: embedding the prompt, searching Redis, or the rest of the call. This change adds OpenTelemetry spans for cache operations and embeddings, and a guide to the whole feature. Together with the two PRs below it, it addresses most of #684; what remains is listed in a comment there.

Changes

A span tree for every cache operation

semantic_cache.check     INTERNAL  redisvl.cache.name, redisvl.cache.result
├── embeddings {model}   CLIENT    gen_ai.operation.name, gen_ai.provider.name,
│                                  gen_ai.request.model, gen_ai.embeddings.dimension.count,
│                                  redisvl.embeddings_cache.result (with an EmbeddingsCache)
└── retrieval {index}    CLIENT    gen_ai.operation.name, gen_ai.data_source.id,
                                   gen_ai.retrieval.top_k, db.system.name, db.collection.name,
                                   db.operation.name,
                                   redisvl.cache.distance_threshold, redisvl.cache.distance

store, update and drop get the same parent span. check and store have an embeddings child unless they are given a precomputed vector. Async methods produce the same trees.

Embeddings spans for every vectorizer

The embeddings span lives in BaseVectorizer, so every vectorizer gains it with no further change, and so do SemanticRouter and SemanticMessageHistory. The four embed methods were re-indented under the span; their behaviour is unchanged.

gen_ai.provider.name uses the registered GenAI value where one exists, and the vectorizer type otherwise. GoogleGenAIVectorizer reports gcp.vertex_ai or gcp.gemini, depending on the backend it resolved.

gen_ai.client.operation.duration is recorded for calls that reach the provider, with error.type on failure. It is not recorded for embeddings-cache hits or cancelled calls. One embed_many call records one point, covering all of its batches.

Errors and content capture

A failure sets an error status and error.type on every span it passes through. The SDK's exception recording is off on every RedisVL span, because the exception message can carry prompt text.

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT controls content capture:

• When it is SPAN_ONLY or SPAN_AND_EVENT, the retrieval span also records the query text and each candidate's entry id and distance.
• true does not turn capture on, unlike in some older GenAI instrumentations.
• Response text is never recorded.

The guide

docs/user_guide/how_to_guides/observability.md covers:

• installing redisvl[otel] with an SDK;
• every span, metric and attribute;
• reading the distance histogram to tune distance_threshold;
• starter PromQL queries;
• turning on redis-py's own metrics alongside;
• content capture and its privacy implications;
• the off switch.

The PromQL names are the ones the OpenTelemetry Prometheus exporter produces. The guide recommends opentelemetry-sdk>=1.32, the first release that exports bucket advice correctly over OTLP, and the tests install that version too. The SDK now comes with the dev dependency group, like every other test dependency, so the separate otel-test group and its --group otel-test flag in make install, CONTRIBUTING and the test matrix are gone.

Notes

• Span kind. Embeddings spans are CLIENT for every vectorizer, including local models (hf, custom) and calls served entirely from the embeddings cache. A full cache hit carries redisvl.embeddings_cache.result=hit and records no gen_ai.client.operation.duration. Span kind can change later without affecting any metric.
• Retrieval span attributes. The retrieval span sets db.operation.name=FT.SEARCH alongside db.system.name=redis, because the Redis database conventions require an operation name on Redis spans, and backends group spans by it.
• Span creation isn't guarded. A tracer, sampler or span processor that raises reaches the caller, as with the OpenTelemetry contrib instrumentations, so a broken SDK setup fails loudly instead of silently dropping traces. Metric recording is guarded, because an older API rejecting bucket advice is a real case.

Release Notes

• SemanticCache can now report OpenTelemetry metrics and spans.
  • Install: pip install "redisvl[otel]", then configure an OpenTelemetry SDK in your application. RedisVL emits nothing until you do.
  • Metrics: operation duration, hit rate and nearest-match distance.
  • Spans: a span tree that separates embedding from vector search.
  • Embeddings spans: every vectorizer now produces embeddings spans and gen_ai.client.operation.duration.
  • Content capture: prompts are recorded only when OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is SPAN_ONLY or SPAN_AND_EVENT.
  • Off switch: set REDISVL_OTEL_DISABLED=true.
  • See the new guide, "Observe the Semantic Cache with OpenTelemetry".

Reviewer Brief

Start here: redisvl/utils/vectorize/_telemetry.py, embeddings(). Every vectorizer's embed call in base.py now runs inside it, so it decides what each provider call records.

Where it could fail

• redisvl/utils/vectorize/base.py:191 and :338: the embeddings-cache result for a batch is computed as len(contents) - len(cache_misses). It stays right only while misses align with inputs, and only the partial case is tested.
• redisvl/extensions/cache/llm/_telemetry.py:140: with content capture on, record_lookup records the prompt and each candidate's entry id and distance. Any field added to documents would go beyond what the guide promises.
• redisvl/utils/otel.py:202 (start_span): this is the one place exception recording is turned off for RedisVL spans. A span started any other way would put exception messages, which can contain prompt text, on the trace.

Not verified: live provider APIs (the provider names and the Google backend mapping are tested with stand-ins); cluster mode; the SDK 1.31.0 and 1.32.0 bucket-advice fixes the guide cites.

Beyond CI: the cancellation and Google-backend regression tests fail against the code before their fixes; an instrumented lookup with no SDK costs about 11 µs on an Apple M4 Pro.

Since the last brief: ee7149df makes the guide's hit-rate query report 0 for a cache that has never hit, instead of dropping it; the query wasn't run against Prometheus. e5efdf61 merges the base after it was restacked onto main; this PR's own diff is unchanged. cf278b32 merges the updated base, which brings in main up to 506b961b (Python 3.15 support); this PR's own diff is unchanged. 37654c3c adds a sentence to the guide's threshold section: the near-miss share counts only misses that found a candidate.

_{Reviewed 5eb8ffdf, fixes in b981f7b2 · Claude Code (claude-opus-5-5) · lenses: correctness, security, design, tests, docs, Redis behaviour}

---

Note

Medium Risk
Extensive instrumentation around caches/embeddings plus new privacy-sensitive span attributes—misconfiguration could leak prompts or break tracing pipelines if OTEL SDK expectations change.

Overview
Semantic instrumentation overhaul — adds full OpenTelemetry span trees for SemanticCache plus retrieval child spans and richer distance capture, wraps every vectorizer embed* path with GenAI-style client spans/histograms, and gates optional prompt logging behind OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.

Docs & developer wiring — introduces docs/user_guide/how_to_guides/observability.md, links it from the how-to index/install guide, bumps dev dependencies to bundle opentelemetry-sdk>=1.32 (including lock/workflow/make instructions dropping the old otel-test group), and backs the feature with broad unit/integration coverage around spans, metrics, privacy toggles, and failure isolation.

Risk summary — touches hot embedding/cache code paths and can leak prompt metadata when capture is enabled; verify downstream SRE/backends tolerate new spans and the histogram/schema upgrades.

^{Reviewed by Cursor Bugbot for commit e57b1e1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T08:47:04.163239Z	5a55eec	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a55eec924

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[limjoobin]

Thanks for the thorough implementation and documentation.

I left two comments that I think are worth addressing:

1. Failures during the OpenTelemetry span lifecycle can prevent the wrapped operation, turn a successful operation into an exception, or replace the original RedisVL exception. I reproduced this using real SDK sampler and processor extension points.
2. gen_ai.retrieval.documents[].score currently receives cosine distance, whose ordering is the reverse of the relevance score OpenTelemetry defines. Since SemanticCache always uses cosine, this can be converted with 1 - distance while retaining the raw distance in the RedisVL-specific attribute.

Otherwise, the sync/async structure, Redis query behaviour, privacy gating, tests, and documentation look solid to me.

[limjoobin]

LGTM, thanks! I verified that span lifecycle failures are now isolated without changing the operation’s outcome, and retrieval document scores now use cosine similarity while preserving the raw distance separately. The regression tests and documentation cover both fixes. This is good to go now!

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c58c42d. Configure here.}