Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .github/workflows/cognee-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: Cognee native tracing adapter

on:
pull_request:
branches: [main, dev]
paths:
- 'python/frameworks/cognee/**'
- 'python/examples/cognee/**'
- 'python/tests/harness/**'
- '.github/workflows/cognee-tests.yml'
push:
branches: [dev]
paths:
- 'python/frameworks/cognee/**'
- 'python/examples/cognee/**'
- 'python/tests/harness/**'
- '.github/workflows/cognee-tests.yml'

permissions:
contents: read

jobs:
compatibility:
runs-on: ubuntu-latest
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
cognee: ['1.6.5', 'latest']
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install adapter and real Cognee
env:
COGNEE_VERSION: ${{ matrix.cognee }}
run: |
python -m pip install './python/frameworks/cognee[dev]'
if [ "$COGNEE_VERSION" = latest ]; then
python -m pip install --upgrade 'cognee[tracing]'
else
python -m pip install "cognee[tracing]==$COGNEE_VERSION"
fi
python -m pip check
- name: Test with loopback only
env:
LITELLM_LOCAL_MODEL_COST_MAP: 'True'
run: |
sudo iptables -I OUTPUT 1 ! -o lo -j REJECT
sudo ip6tables -I OUTPUT 1 ! -o lo -j REJECT
trap 'sudo iptables -D OUTPUT ! -o lo -j REJECT; sudo ip6tables -D OUTPUT ! -o lo -j REJECT' EXIT
python -I -m pytest --noconftest python/frameworks/cognee/tests python/examples/cognee/tests -q
11 changes: 11 additions & 0 deletions python/examples/cognee/tests/test_cognee_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -159,3 +159,14 @@ def do_POST(self):
assert all(secret not in wire for secret in (b"synthetic-model-key", b"synthetic-fi-api", b"synthetic-fi-secret"))
for name, kind in (("memory.retrieve", "RETRIEVER"), ("cognee.observe.acreate_structured_output", "LLM")):
assert any(s.name == name and any(a.key == "fi.span.kind" and a.value.string_value == kind for a in s.attributes) for s in spans)
embeddings = [s for s in spans if any(
a.key == "gen_ai.operation.name" and a.value.string_value == "embeddings"
for a in s.attributes
)]
assert embeddings, "Real Cognee embedding operations must emit native spans"
for span in embeddings:
attrs = {a.key: a.value for a in span.attributes}
assert attrs["fi.span.kind"].string_value == "EMBEDDING"
assert attrs["gen_ai.provider.name"].string_value == "openai"
assert attrs["gen_ai.embeddings.dimension.count"].int_value == 16
assert attrs["gen_ai.request.model"].string_value.endswith("text-embedding-3-small")
6 changes: 3 additions & 3 deletions python/frameworks/cognee/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

Send Cognee's native OpenTelemetry spans to Future AGI without additional instrumentation. Enable `COGNEE_TRACING_ENABLED=true` before your first Cognee operation and configure once before that operation.

Requires Python 3.10–3.13 and `fi-instrumentation-otel>=1.2.2,<2`.
Requires Python 3.10–3.13, Cognee 1.6.5 or later, and `fi-instrumentation-otel>=1.2.2,<2`.

```bash
pip install "cognee[tracing]==1.6.5" "traceai-cognee==0.1.0"
pip install --upgrade "cognee[tracing]>=1.6.5" traceai-cognee
export COGNEE_TRACING_ENABLED=true
export FI_API_KEY="YOUR_FI_API_KEY"
export FI_SECRET_KEY="YOUR_FI_SECRET_KEY"
Expand Down Expand Up @@ -36,4 +36,4 @@ With content capture enabled, the adapter redacts recognized credential field na

This is a field-name policy, not a universal secret detector. Free text and unknown encodings are not scanned for credentials; enable content capture only for approved application data. The adapter does not mutate the original content or inspect opaque runtime objects. Numeric attributes outside the OTLP signed 64-bit integer range, or non-finite floating-point values, are omitted before encoding.

For a complete add/cognify/search application, see the [Cognee example](../../examples/cognee/). Search spans are mapped to `RETRIEVER` and structured-output model calls to `LLM`. Native span IDs, parent relationships and status codes are preserved, including Cognee's missing-collection probe errors.
For a complete add/cognify/search application, see the [Cognee example](../../examples/cognee/). Search spans are mapped to `RETRIEVER`, structured-output model calls to `LLM`, and native `gen_ai.operation.name=embeddings` spans to `EMBEDDING`. Embedding provider, model, and dimension metadata remain available with content capture disabled. An explicit native span-kind attribute takes precedence over inferred kinds. Native span IDs, parent relationships and status codes are preserved, including Cognee's missing-collection probe errors.
4 changes: 3 additions & 1 deletion python/frameworks/cognee/tests/test_adapter.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import json
import unittest
from importlib.metadata import version
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
Expand Down Expand Up @@ -93,4 +94,5 @@ def test_default_exporter_constructs_without_sending(self):
self.assertTrue(handle.force_flush())
handle.shutdown()

def test_version(self): self.assertEqual(__version__, '0.1.0')
def test_version(self):
self.assertEqual(__version__, version('traceai-cognee'))
68 changes: 68 additions & 0 deletions python/frameworks/cognee/tests/test_embedding_projection.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
"""Embedding metadata survives the destination-local privacy projection."""
import pytest
from opentelemetry.exporter.otlp.proto.common.trace_encoder import encode_spans
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter

from traceai_cognee._exporter import project


def native_span(extra=None):
provider = TracerProvider(shutdown_on_exit=False)
sink = InMemorySpanExporter()
provider.add_span_processor(SimpleSpanProcessor(sink))
attrs = {
'gen_ai.operation.name': 'embeddings',
'gen_ai.provider.name': 'openai',
'gen_ai.request.model': 'text-embedding-3-small',
'gen_ai.embeddings.dimension.count': 1536,
'server.address': 'private-model-host.invalid',
'custom.secret': 'synthetic-private-value',
**(extra or {}),
}
try:
with provider.get_tracer('native').start_as_current_span('cognee.observe.embed_text', attributes=attrs):
pass
return sink.get_finished_spans()[0]
finally:
provider.shutdown()


@pytest.mark.parametrize('capture_content', [False, True])
def test_embedding_metadata_kind_and_identity(capture_content):
source = native_span()
before = dict(source.attributes)
projected = project(source, 'embedding-test', capture_content)
assert projected.attributes['gen_ai.provider.name'] == 'openai'
assert projected.attributes['gen_ai.embeddings.dimension.count'] == 1536
assert projected.attributes['gen_ai.operation.name'] == 'embeddings'
assert projected.attributes['gen_ai.request.model'] == 'text-embedding-3-small'
assert projected.attributes['fi.span.kind'] == 'EMBEDDING'
assert projected.context == source.context
assert projected.parent == source.parent
assert dict(source.attributes) == before
assert 'fi.span.kind' not in source.attributes
assert 'server.address' not in projected.attributes
assert 'custom.secret' not in projected.attributes
payload = encode_spans([projected]).SerializeToString()
assert b'synthetic-private-value' not in payload
assert b'private-model-host.invalid' not in payload


@pytest.mark.parametrize('key', ['fi.span.kind', 'gen_ai.span.kind', 'llm.request.type', 'openinference.span.kind'])
def test_embedding_inference_preserves_explicit_kind(key):
projected = project(native_span({key: 'CUSTOM'}), 'embedding-test', False)
assert projected.attributes[key] == 'CUSTOM'
if key != 'fi.span.kind':
assert 'fi.span.kind' not in projected.attributes


def test_new_metadata_uses_existing_wire_and_privacy_guards():
projected = project(native_span({
'gen_ai.provider.name': 'https://host.invalid/?api_key=synthetic-secret',
'gen_ai.embeddings.dimension.count': 2**100,
}), 'embedding-test', False)
assert 'gen_ai.provider.name' not in projected.attributes
assert 'gen_ai.embeddings.dimension.count' not in projected.attributes
assert b'synthetic-secret' not in encode_spans([projected]).SerializeToString()
122 changes: 122 additions & 0 deletions python/frameworks/cognee/tests/test_native_embeddings.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
"""Real Cognee decorators -> adapter -> loopback OTLP, with no model calls.

The separate process owns Cognee/OTel globals and a temporary application home.
Install cognee[tracing] to run this contract (required by cognee-tests.yml).
"""
import importlib.util
from pathlib import Path
import os
import subprocess
import sys
import tempfile

import pytest


PROGRAM = r'''
import asyncio
import json
import sys
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
from traceai_cognee import configure

# Reuse the repository's loopback receiver instead of implementing a collector.
sys.path.insert(0, sys.argv[1])
from harness import Receiver, _flatten_attributes

with Receiver() as receiver:
handle = configure(project_name='cognee-contract', endpoint=receiver.collector_endpoint,
headers={'X-Api-Key': 'synthetic-api', 'X-Secret-Key': 'synthetic-secret'})
raw = InMemorySpanExporter()
handle.provider.add_span_processor(SimpleSpanProcessor(raw))
try:
from cognee.modules.observability.get_observe import get_observe
observe = get_observe()

class Engine:
provider = 'OpenAI'
model = 'text-embedding-3-small'
dimensions = 3
endpoint = 'https://private-model-host.invalid/v1'

@observe(as_type='embeddings')
def embed_text(self, text):
return [0.1, 0.2, 0.3]

@observe(as_type='embeddings')
async def embed_documents(self, texts):
return [[0.1, 0.2, 0.3] for _ in texts]

@observe(as_type='embeddings')
async def fail(self, texts):
raise ValueError('synthetic-private-error')

engine = Engine()
with handle.provider.get_tracer('test').start_as_current_span('parent') as parent:
assert engine.embed_text('synthetic-private-content') == [0.1, 0.2, 0.3]
assert asyncio.run(engine.embed_documents(['synthetic-private-content'])) == [[0.1, 0.2, 0.3]]
try:
asyncio.run(engine.fail(['synthetic-private-content']))
except ValueError:
pass
else:
raise AssertionError('native error was swallowed')
assert handle.force_flush()
exported = receiver.spans()
source = raw.get_finished_spans()
embeddings = [s for s in exported if s['name'].startswith('cognee.observe.')]
native = [s for s in source if s.name.startswith('cognee.observe.')]
assert len(embeddings) == len(native) == 3
assert len({s['spanId'] for s in exported}) == len(exported)
from base64 import b64decode
# Protobuf JSON represents IDs as base64, not the usual hex strings.
def span_id(value):
return int.from_bytes(b64decode(value), 'big')
for span in embeddings:
attrs = _flatten_attributes(span['attributes'])
assert attrs['gen_ai.provider.name'] == 'openai', attrs
assert int(attrs['gen_ai.embeddings.dimension.count']) == 3, attrs
assert attrs['gen_ai.operation.name'] == 'embeddings'
assert attrs['gen_ai.request.model'] == engine.model
assert attrs['fi.span.kind'] == 'EMBEDDING'
assert span_id(span['parentSpanId']) == parent.get_span_context().span_id
assert span_id(span['spanId']) in {s.context.span_id for s in native}
assert int.from_bytes(b64decode(span['traceId']), 'big') == parent.get_span_context().trace_id
failed = next(s for s in embeddings if s['name'] == 'cognee.observe.fail')
assert failed['status']['code'] == 'STATUS_CODE_ERROR'
assert not failed['status'].get('message')
wire = json.dumps(exported)
for private in ('synthetic-private-content', 'synthetic-private-error', 'private-model-host.invalid'):
assert private not in wire
assert all('fi.span.kind' not in s.attributes for s in native)
assert all(s.attributes['server.address'] == 'private-model-host.invalid' for s in native)
for request in receiver.requests():
assert request['path'] == '/tracer/v1/traces'
assert request['headers']['x-api-key'] == 'synthetic-api'
assert request['headers']['x-secret-key'] == 'synthetic-secret'
assert all(r['project_name'] == 'cognee-contract' and r['project_type'] == 'observe'
for r in request['resource_attributes'])
finally:
handle.shutdown()
handle.provider.shutdown()
'''


@pytest.mark.skipif(importlib.util.find_spec('cognee') is None, reason='install cognee[tracing] for the native contract')
def test_native_embedding_decorators_export_once_with_metadata():
harness_parent = Path(__file__).resolve().parents[3] / 'tests'
with tempfile.TemporaryDirectory() as directory:
env = {
'PATH': os.environ.get('PATH', ''),
'HOME': directory,
'COGNEE_TRACING_ENABLED': 'true',
'TELEMETRY_DISABLED': 'true',
'MONITORING_TOOL': 'none',
'LITELLM_LOCAL_MODEL_COST_MAP': 'True',
}
result = subprocess.run(
[sys.executable, '-I', '-c', PROGRAM, str(harness_parent)],
env=env, cwd=directory, capture_output=True, text=True, timeout=120,
)
assert result.returncode == 0, result.stdout + result.stderr
Loading
Loading