Skip to content

docs(cognee): use the maintained native tracing adapter - #1044

Merged
nik13 merged 5 commits into
mainfrom
docs/cognee-maintained-adapter
Nov 9, 2026
Merged

nik13 merged 5 commits into
mainfrom
docs/cognee-maintained-adapter

Conversation

@nik13

@nik13 nik13 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

What changed and why

Replace the copied Cognee exporter/filter recipe with the maintained native-tracing adapter. Developers install published packages, configure once, then run a small add/cognify/search application; they no longer maintain instrumentation source.

  • Pin the reader setup to cognee[tracing]==1.6.6 and the current published traceai-cognee==0.1.1.
  • Configure before Cognee operations, reuse native spans, and flush before shutdown. Explain shared-provider shutdown behavior and preserved native missing-collection errors.
  • Keep content opt-in and error descriptions/stack traces excluded; retain the structured-redaction limits and separate-exporter warning.
  • Explicitly leave OTEL_EXPORTER_OTLP_ENDPOINT unset: Cognee uses it to enable log/metric exporters outside this trace adapter's filtering.
  • Remove copied-helper instructions, stale publication claims and customer-facing QA diaries.
  • Merge main at 970056be6443bff2051fbee1101f5b99de4cda12, preserving both the Cognee contract and all main integration tests. Catalog unchanged; test changes are additive.

Verification on the pushed head

Head: c86b7af692edaeb616aa3b0f081c4c8fd467864b. All tests, installs, builds and browser execution ran in E2B or GitHub Actions, not locally.

Documentation

npm ci
npm run test:integrations
npm run check:integrations
NODE_OPTIONS=--max-old-space-size=6144 npm run build
npm run audit-links
  • 284 passed, zero failed/skipped; integration typecheck passed.
  • The Cognee contract fails against the base page and passes against this head:
    node --test --test-name-pattern='Cognee uses the maintained adapter' scripts/integrations.test.mjs.
  • Astro/Pagefind build passed: 852 pages indexed.
  • Link audit: 0 broken navigation links, 0 broken content links; 31 existing orphan-page warnings outside this change.
  • Desktop Playwright render visually inspected: HTTP 200, all 3 code blocks, no page errors or horizontal overflow, correct package pin and privacy prerequisite. External browser requests blocked. This is a docs screenshot, not a fabricated Future AGI product trace.

Published packages and exact guide snippet

Executed the guide's install command and environment block, then its unchanged Python block with synthetic loopback OpenAI-compatible services and an OTLP/protobuf receiver. The snippet subprocess permits loopback connections only. No provider or Future AGI customer credentials were used.

pip install "cognee[tracing]==1.6.6" "traceai-cognee==0.1.1"
pip check
python -I -m pytest -q python/frameworks/cognee/tests --junitxml=evidence/package-tests.xml
python -I validate_snippet.py

The package tests are staged from traceAI commit 6689782, with the shared receiver fixture. Imports use the installed PyPI adapter; the file-path structured-redaction test also uses the helper copied from that installed package, not an unpublished adapter checkout.

Final-head E2B cell Package tests Exact application and OTLP result
Python 3.13.18, Cognee 1.6.6, traceai-cognee 0.1.1, core 1.3.0 325 passed, no skips; pip check passed 136 spans, one trace, zero duplicate IDs; 61 preserved native error statuses
Python 3.10.22, Cognee 1.6.5, traceai-cognee 0.1.1, core 1.3.0 325 passed, no skips; pip check passed 120 spans, one trace, zero duplicate IDs; 60 preserved native error statuses

The second cell additionally installs pip install "cognee[tracing]==1.6.5" to exercise the adapter's lower Cognee bound. The reader-pinned Cognee 1.6.6 setup was also run on Python 3.10 and passed with 136 spans before the prose-only privacy-prerequisite addition; final-head rows above are separately identified.

Both final cells verify LLM, RETRIEVER and EMBEDDING mappings, project/resource fields and auth headers, excluded document/question/answer content, and excluded error descriptions/stack traces. Empty sanitized exception events are retained by design. Model requests reach only loopback /v1/chat/completions and /v1/embeddings.

E2B receipt labels: qw-docs-1044-docs-final, qw-docs-1044-py310-final, qw-docs-1044-py313-final; all exit 0 and sandbox deletion is confirmed. Earlier harness-only failures were corrected and rerun: Node's default 2 GiB heap, a preview-startup race, and an overly strict assertion that incorrectly prohibited sanitized empty exception events.

GitHub checks

All 6 checks passed on the pushed head:

git diff --check and JavaScript syntax validation passed. E2E coverage marker: not applicable; this docs repository has no e2e/scripts/e2e-coverage.mjs harness.

Scope and readiness

Published-package and loopback qualification only; no real-provider or Future AGI Cloud ingestion run is claimed. No package release, merge, approval or branch rename is part of this PR. The PR is ready for review; required human approval remains in place.

🤖 Generated with Claude Code

Co-Authored-By: Claude Code <noreply@anthropic.com>
nik13 and others added 2 commits November 1, 2026 23:01
Co-Authored-By: Claude Code <noreply@anthropic.com>

# Conflicts:
#	scripts/integrations.test.mjs
Co-Authored-By: Claude Code <noreply@anthropic.com>
nik13 and others added 2 commits November 9, 2026 14:46
Preserve the Cognee and main integration contracts while updating the maintained adapter to the published 0.1.1 release.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Keep the generic OTLP endpoint unset so Cognee does not enable log and metric exporters outside the maintained trace adapter privacy filter.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit a050073 into main Nov 9, 2026
6 checks passed
@nik13
nik13 deleted the docs/cognee-maintained-adapter branch November 9, 2026 23:37
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.

1 participant