Skip to content

docs: improve alternative backend and client discoverability#1985

Open
axelray-dev wants to merge 4 commits into
pydantic:mainfrom
axelray-dev:axelray-dev/fix-logfire-484-alt-doc-search
Open

docs: improve alternative backend and client discoverability#1985
axelray-dev wants to merge 4 commits into
pydantic:mainfrom
axelray-dev:axelray-dev/fix-logfire-484-alt-doc-search

Conversation

@axelray-dev

@axelray-dev axelray-dev commented Jun 1, 2026

Copy link
Copy Markdown

Fixes #484

What changed

Three minimal docs-only edits to improve search discoverability for alternative backends and alternative clients:

  1. docs/how-to-guides/alternative-backends.md: Added a sentence after the intro paragraph mentioning searchable keywords ("self-hosted backend", "collector", "Jaeger", "Grafana Tempo", "OTLP-compatible server").

  2. docs/how-to-guides/alternative-clients.md: Added language examples after "first-class supported languages": Go, Ruby, OpenTelemetry SDK. (Node.js and Rust removed from examples since they have first-class SDKs per docs/languages.md.)

  3. docs/why.md: Replaced the vague "cross-language data integration and data export to any OpenTelemetry-compatible backend or proxy" with explicit links to the Alternative Clients and Alternative Backends pages, mentioning Node.js, Rust, Go, Jaeger, and Grafana Tempo.

Why this helps search/discoverability

The docs site uses Algolia search (alt-logfire-docs index). Users searching for "opentelemetry server", "self-hosted backend", "OTLP", "Jaeger", "collector", "Go", "Ruby", or "alternative clients" will now find these pages more easily because:

  • The new keywords appear in the page body text (which Algolia indexes)
  • The OpenTelemetry section in why.md now links directly to both pages, creating discoverable cross-references
  • The language examples in alternative-clients.md match common search queries

Checks run

make lint          # passed, 243 files already formatted
make format        # 243 files left unchanged

Skipped checks

  • No local MkDocs build (docs are rendered by the pydantic/unified-docs pipeline, not locally).
  • No code changes. This is docs-only, so no tests were needed.

@axelray-dev axelray-dev marked this pull request as ready for review June 1, 2026 14:13
@codecov

codecov Bot commented Jun 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 3 files

Confidence score: 4/5

  • This PR is likely safe to merge with minimal risk because the reported issue is documentation-only and does not indicate runtime or functional regression.
  • The main concern is a user-facing docs inconsistency: docs/how-to-guides/alternative-clients.md says Node.js and Rust are outside first-class support, which conflicts with docs/languages.md and the page’s own SDK references.
  • Given the moderate severity (5/10) but high confidence (9/10), this is worth correcting soon to avoid reader confusion about supported languages.
  • Pay close attention to docs/how-to-guides/alternative-clients.md and docs/languages.md - ensure language support statements are consistent across docs.

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread docs/how-to-guides/alternative-clients.md Outdated
Comment on lines +7 to +9
**Logfire** uses the OpenTelemetry standard. This means that you can configure the SDK to export to any backend that supports OpenTelemetry.

This is useful when you want to send telemetry to a self-hosted backend or collector, such as Jaeger, Grafana Tempo, or any other OTLP-compatible server.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these two lines overlap too much. if this PR is AI generated, please give it a human review.

@axelray-dev

Copy link
Copy Markdown
Author

Thanks, you're right. I reviewed the wording and removed the overlap so the added docs links are more direct.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 2 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread docs/why.md Outdated
axelray-dev and others added 4 commits June 5, 2026 00:56
Fixes pydantic#484

- alternative-backends.md: add keywords for search indexing
  (self-hosted backend, collector, Jaeger, Grafana Tempo, OTLP-compatible server)
- alternative-clients.md: add language examples for search indexing
  (Node.js, Rust, Go, Ruby, OpenTelemetry SDK)
- why.md: replace vague 'cross-language data integration' with explicit
  links to Alternative Clients and Alternative Backends pages
These languages have custom first-class SDKs per docs/languages.md.
Keep only Go, Ruby, and generic OpenTelemetry SDK languages as examples
of languages outside first-class support.
@axelray-dev axelray-dev force-pushed the axelray-dev/fix-logfire-484-alt-doc-search branch from 2e8e678 to b1f9216 Compare June 4, 2026 16:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve search for alternative backends/clients

2 participants