From 108e4d84de220e9593faaa48ed9f4e8648f7e5ac Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 1 Nov 2026 23:34:40 -0800 Subject: [PATCH 1/2] docs(crewai): use native OpenTelemetry for lifecycle coverage Replace the limited wrapper-first setup with CrewAI's published native tracing session. Cover sync/async crews and agents, Flows, model calls, failures, cleanup, concurrency and real OTLP wire contracts across the supported native floor and latest release. Co-Authored-By: Claude Code --- .github/workflows/crewai-docs.yml | 41 ++ scripts/crewai-native.test.py | 398 ++++++++++++++++++ scripts/crewai-page.test.mjs | 35 ++ src/lib/integrations.mjs | 2 +- .../docs/integrations/traceai/crewai.mdx | 151 ++++--- 5 files changed, 569 insertions(+), 58 deletions(-) create mode 100644 .github/workflows/crewai-docs.yml create mode 100644 scripts/crewai-native.test.py create mode 100644 scripts/crewai-page.test.mjs diff --git a/.github/workflows/crewai-docs.yml b/.github/workflows/crewai-docs.yml new file mode 100644 index 000000000..2525c1cee --- /dev/null +++ b/.github/workflows/crewai-docs.yml @@ -0,0 +1,41 @@ +name: CrewAI native tracing documentation + +on: + pull_request: + branches: [main] + paths: + - src/pages/docs/integrations/traceai/crewai.mdx + - scripts/crewai-*.test.* + - .github/workflows/crewai-docs.yml + +permissions: + contents: read + +jobs: + native-tracing: + name: Native tracing (Python ${{ matrix.python }}, CrewAI ${{ matrix.crewai }}) + runs-on: ubuntu-latest + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + python: ['3.10', '3.13'] + crewai: ['==1.15.33', '>=1.15.33,<2'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - uses: actions/setup-node@v4 + with: + node-version: '20' + - name: Install published native dependencies + run: python -m pip install 'crewai${{ matrix.crewai }}' opentelemetry-exporter-otlp-proto-http 'pytest>=8,<10' + - name: Check page contracts + run: node --test scripts/crewai-page.test.mjs + - name: Run native snippets with loopback networking only + run: | + TEST_PYTHON="$(command -v python)" + TEST_HOME="$(mktemp -d)" + sudo env TEST_PYTHON="$TEST_PYTHON" TEST_HOME="$TEST_HOME" \ + unshare --net sh -c 'ip link set lo up; env -i PATH=/usr/bin:/bin HOME="$TEST_HOME" "$TEST_PYTHON" -I -m pytest --noconftest --import-mode=importlib -q scripts/crewai-native.test.py' diff --git a/scripts/crewai-native.test.py b/scripts/crewai-native.test.py new file mode 100644 index 000000000..697f99493 --- /dev/null +++ b/scripts/crewai-native.test.py @@ -0,0 +1,398 @@ +"""Native CrewAI contract tests. Synthetic credentials and loopback HTTP only. + +Run with pytest inside a network-denied sandbox (loopback allowed). No traceAI +instrumentor, patched LLM methods, or real provider credentials are used. +""" + +import asyncio +import errno +import json +import os +import re +import socket +import threading +from contextlib import contextmanager +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from uuid import uuid4 + +import pytest +from google.protobuf.json_format import MessageToDict +from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter +from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ( + ExportTraceServiceRequest, +) +from opentelemetry.sdk.resources import Resource + +# Set before imports: product analytics and CrewAI-hosted tracing are independent +# of the explicitly owned native OTLP session below. +os.environ.update( + CREWAI_DISABLE_TELEMETRY="true", + CREWAI_DISABLE_TRACKING="true", + CREWAI_TRACING_ENABLED="false", + OTEL_SDK_DISABLED="false", + OPENAI_API_KEY="synthetic-openai-config-canary", +) + +from crewai import Agent, Crew, LLM, Task +from crewai.events import crewai_event_bus +from crewai.flow.flow import Flow, listen, start +from crewai.telemetry.tracing import telemetry_session + + +class LocalServer: + """Collect OTLP protobuf and serve deterministic OpenAI completions.""" + + def __init__(self): + self.spans = [] + self.resources = [] + self.headers = [] + self.prompts = [] + self.fail = False + owner = self + + class Handler(BaseHTTPRequestHandler): + def do_POST(self): + body = self.rfile.read(int(self.headers["Content-Length"])) + if self.path == "/tracer/v1/traces": + request = ExportTraceServiceRequest.FromString(body) + data = MessageToDict(request) + owner.headers.append(dict(self.headers)) + for resource in data["resourceSpans"]: + owner.resources.append(attrs(resource["resource"])) + for scope in resource["scopeSpans"]: + owner.spans.extend(scope["spans"]) + response = b"" + status = 200 + elif self.path == "/v1/chat/completions": + owner.prompts.append(json.loads(body)) + if owner.fail: + response = json.dumps( + { + "error": { + "message": "synthetic model failure", + "type": "invalid_request_error", + } + } + ).encode() + status = 400 + else: + response = json.dumps( + { + "id": "synthetic-completion", + "object": "chat.completion", + "created": 1, + "model": "gpt-4o-mini", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Final Answer: Useful answer", + }, + "finish_reason": "stop", + } + ], + "usage": { + "prompt_tokens": 11, + "completion_tokens": 5, + "total_tokens": 16, + }, + } + ).encode() + status = 200 + else: + self.send_error(404) + return + self.send_response(status) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(response))) + self.end_headers() + self.wfile.write(response) + + def log_message(self, *_args): + pass + + self.http = ThreadingHTTPServer(("127.0.0.1", 0), Handler) + self.origin = f"http://127.0.0.1:{self.http.server_port}" + self.thread = threading.Thread(target=self.http.serve_forever, daemon=True) + self.thread.start() + + def close(self): + self.http.shutdown() + self.http.server_close() + self.thread.join() + + +def attrs(span): + return { + item["key"]: next(iter(item["value"].values())) + for item in span.get("attributes", []) + } + + +@pytest.fixture +def server(): + value = LocalServer() + try: + yield value + finally: + value.close() + + +@contextmanager +def session(server): + exporter = OTLPSpanExporter( + endpoint=server.origin + "/tracer/v1/traces", + headers={ + "X-Api-Key": "synthetic-fi-key", + "X-Secret-Key": "synthetic-fi-secret", + }, + ) + with telemetry_session( + str(uuid4()), + "crewai_project", + exporters=[exporter], + resource=Resource( + { + "service.name": "crewai-app", + "project_name": "crewai_project", + "project_type": "observe", + } + ), + ): + yield + + +def agent(server): + llm = LLM( + model="openai/gpt-4o-mini", + base_url=server.origin + "/v1", + api_key=os.environ["OPENAI_API_KEY"], + ) + return Agent( + role="Writer", + goal="Write a useful answer", + backstory="A concise writer", + llm=llm, + allow_delegation=False, + ) + + +class ExampleFlow(Flow): + @start() + def prepare(self): + return "Useful input" + + @listen(prepare) + def finish(self, text): + return text + " and output" + + +def assert_transport(server): + assert server.spans + assert len({s["spanId"] for s in server.spans}) == len(server.spans) + assert all( + int(s["endTimeUnixNano"]) >= int(s["startTimeUnixNano"]) > 0 + for s in server.spans + ) + for headers in server.headers: + lowered = {k.lower(): v for k, v in headers.items()} + assert lowered["x-api-key"] == "synthetic-fi-key" + assert lowered["x-secret-key"] == "synthetic-fi-secret" + assert lowered["content-type"] == "application/x-protobuf" + assert all( + r["project_name"] == "crewai_project" and r["project_type"] == "observe" + for r in server.resources + ) + # Configuration credentials stay in HTTP headers, not span content. + payload = json.dumps(server.spans) + for canary in ( + "synthetic-openai-config-canary", + "synthetic-fi-key", + "synthetic-fi-secret", + ): + assert canary not in payload + + +def test_outbound_network_is_denied(): + with socket.socket() as connection: + connection.settimeout(1) + with pytest.raises(OSError) as error: + connection.connect(("192.0.2.1", 443)) + assert error.value.errno in (errno.EPERM, errno.EACCES, errno.ENETUNREACH) + + +def test_native_flow_sync_and_async(server): + for async_run in (False, True): + start_index = len(server.spans) + with session(server): + flow = ExampleFlow() + result = asyncio.run(flow.kickoff_async()) if async_run else flow.kickoff() + assert result == "Useful input and output" + spans = server.spans[start_index:] + roots = [ + s + for s in spans + if attrs(s).get("gen_ai.operation.name") == "invoke_workflow" + ] + methods = [ + s + for s in spans + if attrs(s).get("gen_ai.operation.name") == "execute_method" + ] + assert len(roots) == 1 and len(methods) == 2 + assert len(spans) == 3 + assert all( + s["parentSpanId"] == roots[0]["spanId"] + and s["traceId"] == roots[0]["traceId"] + for s in methods + ) + assert "Useful input and output" in attrs(roots[0])["gen_ai.output.messages"] + assert_transport(server) + + +@pytest.mark.parametrize("standalone", [False, True]) +@pytest.mark.parametrize("async_run", [False, True]) +def test_native_agent_and_model(server, standalone, async_run): + with session(server): + writer = agent(server) + if standalone: + result = ( + asyncio.run(writer.kickoff_async("Write a useful answer")) + if async_run + else writer.kickoff("Write a useful answer") + ) + else: + task = Task( + description="Write a useful answer", + expected_output="One sentence", + agent=writer, + ) + crew = Crew(agents=[writer], tasks=[task]) + result = asyncio.run(crew.kickoff_async()) if async_run else crew.kickoff() + assert "Useful answer" in result.raw + assert len(server.prompts) == 1 + llms = [s for s in server.spans if attrs(s).get("gen_ai.operation.name") == "chat"] + agents = [ + s + for s in server.spans + if attrs(s).get("gen_ai.operation.name") == "invoke_agent" + ] + assert len(llms) == len(agents) == 1 + assert llms[0]["parentSpanId"] == agents[0]["spanId"] + if not standalone: + crews = [ + s + for s in server.spans + if attrs(s).get("gen_ai.operation.name") == "invoke_workflow" + ] + tasks = [ + s + for s in server.spans + if attrs(s).get("gen_ai.operation.name") == "execute_task" + ] + assert len(crews) == len(tasks) == 1 + assert tasks[0]["parentSpanId"] == crews[0]["spanId"] + assert agents[0]["parentSpanId"] == tasks[0]["spanId"] + assert len({s["traceId"] for s in server.spans}) == 1 + values = attrs(llms[0]) + assert values["gen_ai.request.model"] == "gpt-4o-mini" + assert values["gen_ai.provider.name"] == "openai" + assert int(values["gen_ai.usage.input_tokens"]) == 11 + assert int(values["gen_ai.usage.output_tokens"]) == 5 + assert "Write a useful answer" in values["gen_ai.input.messages"] + assert "Useful answer" in values["gen_ai.output.messages"] + assert_transport(server) + + +def test_native_model_failure_closes_span(server): + server.fail = True + with pytest.raises(Exception, match="synthetic model failure"): + with session(server): + agent(server).llm.call("Write a useful answer") + llms = [s for s in server.spans if attrs(s).get("gen_ai.operation.name") == "chat"] + assert len(llms) == 1 + assert llms[0]["status"]["code"] == "STATUS_CODE_ERROR" + assert_transport(server) + + +def test_native_flow_failure_and_session_cleanup(server): + class BrokenFlow(Flow): + @start() + def fail(self): + raise ValueError("synthetic flow failure") + + with pytest.raises(ValueError, match="synthetic flow failure"): + with session(server): + BrokenFlow().kickoff() + assert len(server.spans) == 2 + assert all(s["status"]["code"] == "STATUS_CODE_ERROR" for s in server.spans) + count = len(server.spans) + ExampleFlow().kickoff() + crewai_event_bus.flush(timeout=10) + assert len(server.spans) == count # The closed session no longer listens. + assert_transport(server) + + +def test_overlapping_sessions_keep_distinct_traces(server): + class AsyncFlow(Flow): + @start() + async def prepare(self): + await asyncio.sleep(0.02) + return "Useful output" + + async def run_one(): + with session(server): + return await AsyncFlow().kickoff_async() + + async def run_both(): + return await asyncio.gather(run_one(), run_one()) + + assert asyncio.run(run_both()) == ["Useful output", "Useful output"] + assert len(server.spans) == 4 + roots = [ + s + for s in server.spans + if attrs(s).get("gen_ai.operation.name") == "invoke_workflow" + ] + assert len(roots) == 2 + assert len({s["traceId"] for s in roots}) == 2 + for root in roots: + children = [s for s in server.spans if s.get("parentSpanId") == root["spanId"]] + assert len(children) == 1 and children[0]["traceId"] == root["traceId"] + assert_transport(server) + + +def test_documented_python_snippets(server, monkeypatch): + page = ( + Path(__file__).parent.parent / "src/pages/docs/integrations/traceai/crewai.mdx" + ).read_text() + snippets = re.findall(r"```python\n(.*?)```", page, re.S) + assert len(snippets) == 2 + monkeypatch.setenv("FI_API_KEY", "synthetic-fi-key") + monkeypatch.setenv("FI_SECRET_KEY", "synthetic-fi-secret") + monkeypatch.setenv("OPENAI_MODEL", "openai/gpt-4o-mini") + monkeypatch.setenv("OPENAI_BASE_URL", server.origin + "/v1") + # The only code substitution is the collector destination. The documented + # credentials, Resource, native session and complete application run as-is. + code = snippets[0].replace( + "https://api.futureagi.com/tracer/v1/traces", + server.origin + "/tracer/v1/traces", + ) + scope = {"__name__": __name__} + exec(compile(code, "crewai_example.py", "exec"), scope) + assert "Useful answer" in scope["result"].raw + assert ( + len( + [s for s in server.spans if attrs(s).get("gen_ai.operation.name") == "chat"] + ) + == 1 + ) + exec(compile(snippets[1], "crewai_flow_example.py", "exec"), scope) + with session(server): + result = scope["ExplanationFlow"]().kickoff() + assert result == { + "summary": "Distributed tracing connects the steps in an agent workflow." + } + assert_transport(server) diff --git a/scripts/crewai-page.test.mjs b/scripts/crewai-page.test.mjs new file mode 100644 index 000000000..a234fee8c --- /dev/null +++ b/scripts/crewai-page.test.mjs @@ -0,0 +1,35 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; + +const page = readFileSync(new URL('../src/pages/docs/integrations/traceai/crewai.mdx', import.meta.url), 'utf8'); +const [native, legacy = ''] = page.split('## Existing traceAI installations'); + +test('CrewAI leads with the published native lifecycle route', () => { + assert.match(native, /crewai>=1\.15\.33/); + assert.match(native, /opentelemetry-exporter-otlp-proto-http/); + assert.match(native, /from crewai\.telemetry\.tracing import telemetry_session/); + assert.match(native, /with telemetry_session\(/); + assert.match(native, /"https:\/\/api\.futureagi\.com\/tracer\/v1\/traces"/); + assert.match(native, /"X-Api-Key": os\.environ\["FI_API_KEY"\]/); + assert.match(native, /"X-Secret-Key": os\.environ\["FI_SECRET_KEY"\]/); + assert.match(native, /"project_name": "crewai_project"/); + assert.match(native, /"project_type": "observe"/); + assert.doesNotMatch(native, /CrewAIInstrumentor\(\)|class .*Exporter|def .*export/); +}); + +test('native privacy and duplicate-span boundaries are actionable', () => { + assert.match(native, /CREWAI_DISABLE_TELEMETRY=true/); + assert.match(native, /CREWAI_TRACING_ENABLED=false/); + assert.match(native, /Do not.*instrumentor.*same execution/s); + assert.match(native, /FI_HIDE_INPUTS.*FI_HIDE_OUTPUTS.*do not apply/s); + assert.match(native, /state.*error/s); +}); + +test('existing package users retain their supported route and scope', () => { + assert.match(legacy, /traceAI-crewai>=0\.1\.10/); + assert.match(legacy, /Flow.*standalone.*model/s); + assert.match(legacy, /0\.41\.1.*telemetry.*upgrade/s); + assert.match(legacy, /FI_HIDE_INPUTS/); + assert.doesNotMatch(page, /verified live|PASS\/FAIL|test dates|class SanitizingExporter/i); +}); diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index 7988e9d6a..13713bdba 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -74,7 +74,7 @@ export const integrations = [ { id: 'llamaindex-workflows', name: 'LlamaIndex Workflows', href: '/docs/integrations/traceai/llamaindex-workflows', category: 'frameworks', summary: 'Capture steps in event-driven agent workflows.', method: 'traceAI SDK', logo: 'llamaindex' }, { id: 'openai-agents', name: 'OpenAI Agents SDK', href: '/docs/integrations/traceai/openai_agents', category: 'frameworks', summary: 'Trace agent runs, handoffs and tools.', method: 'traceAI SDK', logo: 'openai' }, { id: 'google-adk', name: 'Google ADK', href: '/docs/integrations/traceai/google_adk', category: 'frameworks', summary: 'Instrument agents built with Google ADK for Python.', method: 'traceAI SDK', logo: 'google', aliases: ['Agent Development Kit'] }, - { id: 'crewai', name: 'CrewAI', href: '/docs/integrations/traceai/crewai', category: 'frameworks', summary: 'Follow tasks and tools across a crew of agents.', method: 'traceAI SDK', logo: 'crewai' }, + { id: 'crewai', name: 'CrewAI', href: '/docs/integrations/traceai/crewai', category: 'frameworks', summary: 'Trace crews, standalone agents, Flows and model calls.', method: 'Native OTLP', logo: 'crewai' }, { id: 'autogen', name: 'AutoGen', href: '/docs/integrations/traceai/autogen', category: 'frameworks', summary: 'Trace conversations between AutoGen agents.', method: 'traceAI SDK', logo: 'autogen' }, { id: 'haystack', name: 'Haystack', href: '/docs/integrations/traceai/haystack', category: 'frameworks', summary: 'Trace component execution in Haystack pipelines.', method: 'traceAI SDK', logo: 'haystack' }, { id: 'dspy', name: 'DSPy', href: '/docs/integrations/traceai/dspy', category: 'frameworks', summary: 'Capture DSPy module and language model calls.', method: 'traceAI SDK', logo: 'dspy' }, diff --git a/src/pages/docs/integrations/traceai/crewai.mdx b/src/pages/docs/integrations/traceai/crewai.mdx index 0a09a1f92..80ae42b05 100644 --- a/src/pages/docs/integrations/traceai/crewai.mdx +++ b/src/pages/docs/integrations/traceai/crewai.mdx @@ -1,99 +1,136 @@ --- -title: "CrewAI Integration with Future AGI for Multi-Agent Tracing" -description: "Integrate CrewAI with Future AGI observability. Set up traceAI-crewai to trace multi-agent crew task execution and tool usage automatically." +title: "CrewAI tracing" +description: "Send CrewAI's native crew, task, agent, Flow and model-call spans to Future AGI over OpenTelemetry." --- -Trace CrewAI crew and task execution in **Observe**. This example runs one writing task without external tools. +Trace crews, standalone agents, Flows and model calls in **Observe** using CrewAI's native OpenTelemetry session. ## Install -Use Python 3.10–3.12, as required by the [traceAI-crewai package](https://pypi.org/pypi/traceAI-crewai/0.1.8/json). +Use Python 3.10–3.13 and CrewAI 1.15.33 or newer. ```bash -pip install 'traceAI-crewai==0.1.8' 'crewai>=0.41.1' +pip install 'crewai>=1.15.33,<2' opentelemetry-exporter-otlp-proto-http ``` ---- +This route uses CrewAI's event lifecycle directly. You do not need `traceAI-crewai` or a copied tracing helper. -## Set credentials and capture preferences +## Configure credentials and destinations -Set credentials in your shell, then run the Python blocks below in one script. Choose an OpenAI model available to your account. +Set your Future AGI credentials and an OpenAI model available to your account before importing CrewAI. ```bash -export OPENAI_API_KEY="your-openai-api-key" -export OPENAI_MODEL="your-available-openai-model" export FI_API_KEY="your-futureagi-api-key" export FI_SECRET_KEY="your-futureagi-secret-key" +export OPENAI_API_KEY="your-openai-api-key" +export OPENAI_MODEL="openai/gpt-4o-mini" + +# Turn off CrewAI's separate analytics and hosted trace destination. +export CREWAI_DISABLE_TELEMETRY=true +export CREWAI_TRACING_ENABLED=false ``` -Tracing can export task inputs, outputs and tool data to Future AGI. To hide input and output values and messages, set `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true` before initializing instrumentation. See [mask span attributes](/docs/sdk/tracing/mask-span-attributes) for controls. These switches are not a general scrubber for custom attributes or exception text; keep secrets out of task data and error messages. +The explicit session below still sends spans to Future AGI. Do not enable another CrewAI or model-client instrumentor for the same execution: native sessions already create model-call spans, and combining routes can duplicate them. ---- +**Content capture:** native sessions export application inputs, outputs, Flow state and error details. Keep credentials and sensitive data out of these fields, including tool results and exception messages. `FI_HIDE_INPUTS` and `FI_HIDE_OUTPUTS` do not apply to CrewAI's native provider. If you require content filtering, send through an OpenTelemetry Collector with your organization's redaction policy before forwarding to Future AGI; do not assume the traceAI privacy settings cover this route. -## Register the trace provider +## Run a traced crew -Name the Observe project that will receive spans. +Save this as `crewai_example.py`. The OpenTelemetry exporter sends OTLP/HTTP protobuf to Future AGI; the resource selects your Observe project. ```python -from fi_instrumentation import register -from fi_instrumentation.fi_types import ProjectType - -trace_provider = register( - project_type=ProjectType.OBSERVE, - project_name="crewai_project", +import os +from uuid import uuid4 + +from crewai import Agent, Crew, LLM, Task +from crewai.telemetry.tracing import telemetry_session +from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter +from opentelemetry.sdk.resources import Resource + +exporter = OTLPSpanExporter( + endpoint="https://api.futureagi.com/tracer/v1/traces", + headers={ + "X-Api-Key": os.environ["FI_API_KEY"], + "X-Secret-Key": os.environ["FI_SECRET_KEY"], + }, ) +resource = Resource({ + "service.name": "crewai-app", + "project_name": "crewai_project", + "project_type": "observe", +}) + +writer = Agent( + role="Writer", + goal="Explain technical ideas clearly", + backstory="You write concise explanations for developers.", + llm=LLM(model=os.environ["OPENAI_MODEL"]), + allow_delegation=False, +) +task = Task( + description="Explain why distributed tracing helps debug an agent workflow.", + expected_output="A two-sentence explanation.", + agent=writer, +) +crew = Crew(agents=[writer], tasks=[task]) + +with telemetry_session( + str(uuid4()), + "crewai_project", + exporters=[exporter], + resource=resource, +): + result = crew.kickoff() + print(result.raw) ``` ---- +```bash +python crewai_example.py +``` -## Instrument CrewAI +Exiting `telemetry_session` drains the event handlers, finishes pending spans, flushes the exporter and removes that session's listeners. Create a new session and exporter for each independent execution; do not reuse a shut-down exporter. -Initialize the instrumentor before running the crew. +## Trace a standalone agent or Flow -```python -from traceai_crewai import CrewAIInstrumentor +For a standalone agent, replace the `crew.kickoff()` call inside the session with `writer.kickoff("Explain distributed tracing in two sentences.")`. Keep the call inside the session so its agent and model spans share the same execution. -CrewAIInstrumentor().instrument(tracer_provider=trace_provider) -``` +For a Flow, define the Flow in the same script, then replace the session's two execution lines with `print(ExplanationFlow().kickoff())`. The Flow and each executed method get their own spans. ---- +```python +from crewai.flow.flow import Flow, listen, start -## Run a crew +class ExplanationFlow(Flow): + @start() + def topic(self): + return "Distributed tracing connects the steps in an agent workflow." -```python -import os -from crewai import LLM, Agent, Crew, Task + @listen(topic) + def summarize(self, explanation): + return {"summary": explanation} +``` -def story_example(): - llm = LLM(model=os.environ["OPENAI_MODEL"]) +In async code, keep the session open while awaiting `flow.kickoff_async()` or `writer.kickoff_async(...)`. Do not start background work that outlives the session. - writer = Agent( - role="Writer", - goal="Write creative stories", - backstory="You are a creative writer with a passion for storytelling", - allow_delegation=False, - llm=llm, - ) +## View the trace - writing_task = Task( - description="Write a short story about a magical forest", - agent=writer, - expected_output="A short story about a magical forest", - ) +Open **Observe** in Future AGI and select **crewai_project**. Expand the trace to inspect the execution hierarchy, durations and errors. Model spans include the model name and token usage when the provider reports it. Native content is carried in `gen_ai.input.messages`, `gen_ai.output.messages` and `crewai.*` span attributes. - crew = Crew(agents=[writer], tasks=[writing_task]) +## Existing traceAI installations - # Execute the crew - result = crew.kickoff() - print(result) +You can keep the maintained wrapper route for existing crew/task/tool workloads. Use Python 3.10–3.12 and upgrade the package rather than retaining an older pinned release: -if __name__ == "__main__": - try: - story_example() - finally: - trace_provider.shutdown() # Send pending spans before this script exits. +```bash +pip install --upgrade 'traceAI-crewai>=0.1.10' ``` -## View the trace +This route wraps crew kickoff, task execution and tool usage. It does not add Flow, standalone-agent or model lifecycle spans; use the native session above for those paths. Do not run both tracing routes together. + +Configure the wrapper route using [the package README](https://github.com/future-agi/traceAI/tree/dev/python/frameworks/crewai). Its `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true` controls apply to wrapper-captured content; see [mask span attributes](/docs/sdk/tracing/mask-span-attributes). They do not control CrewAI's independent exporters. + +CrewAI 0.41.1 has no native telemetry opt-out: upgrade CrewAI if you need to disable its separate analytics exporter. On maintained releases, set `CREWAI_DISABLE_TELEMETRY=true` before importing it. + +## Troubleshooting -In Future AGI, open **Observe** and select the project configured above to inspect the trace. +- **No spans arrive:** keep execution inside `telemetry_session`, let the context exit, and check that both Future AGI headers are set. Use the full `/tracer/v1/traces` HTTP endpoint, not a gRPC endpoint. +- **Duplicate model spans:** remove other CrewAI and model-client instrumentors from this execution and disable CrewAI-hosted tracing with `CREWAI_TRACING_ENABLED=false`. +- **Native session import fails:** upgrade CrewAI to the version range in the install command and restart the Python process. From 0ac4573ea5f2a5fca2a599b86e3f94305b0fe0f3 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 2 Nov 2026 00:36:25 -0800 Subject: [PATCH 2/2] fix(crewai): require filtered native lifecycle export Route native CrewAI spans through the documented Collector transform before export. Remove runtime function and callback configuration and map native lifecycle operations to existing Future AGI observation types. Exercise the actual Collector and production converter in floor/latest CI. Co-Authored-By: Claude Code --- .github/workflows/crewai-docs.yml | 34 ++- scripts/crewai-ingestion-check/main.go | 34 +++ scripts/crewai-native.test.py | 207 ++++++++++++++++-- scripts/crewai-page.test.mjs | 22 +- .../docs/integrations/traceai/crewai.mdx | 77 +++++-- 5 files changed, 336 insertions(+), 38 deletions(-) create mode 100644 scripts/crewai-ingestion-check/main.go diff --git a/.github/workflows/crewai-docs.yml b/.github/workflows/crewai-docs.yml index 2525c1cee..f5c1efbc9 100644 --- a/.github/workflows/crewai-docs.yml +++ b/.github/workflows/crewai-docs.yml @@ -6,6 +6,7 @@ on: paths: - src/pages/docs/integrations/traceai/crewai.mdx - scripts/crewai-*.test.* + - scripts/crewai-ingestion-check/** - .github/workflows/crewai-docs.yml permissions: @@ -31,11 +32,40 @@ jobs: node-version: '20' - name: Install published native dependencies run: python -m pip install 'crewai${{ matrix.crewai }}' opentelemetry-exporter-otlp-proto-http 'pytest>=8,<10' + - name: Download the documented Collector Contrib release + run: | + mkdir -p "$RUNNER_TEMP/crewai-collector" + cd "$RUNNER_TEMP/crewai-collector" + ASSET=otelcol-contrib_0.164.0_linux_amd64.tar.gz + URL=https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.164.0 + curl --fail --location --retry 3 "$URL/$ASSET" -o "$ASSET" + curl --fail --location --retry 3 "$URL/$ASSET.sha256" -o "$ASSET.sha256" + printf '%s %s\n' "$(cat "$ASSET.sha256")" "$ASSET" | sha256sum --check + tar -xzf "$ASSET" otelcol-contrib + echo "CREWAI_COLLECTOR=$RUNNER_TEMP/crewai-collector/otelcol-contrib" >> "$GITHUB_ENV" + - name: Check out the production ingestion contract + uses: actions/checkout@v4 + with: + repository: future-agi/future-agi + ref: ee01c07fd6d7e9b1805944883350b2d0064c2b42 + path: .test-deps/future-agi + sparse-checkout: fi-collector + persist-credentials: false + - uses: actions/setup-go@v5 + with: + go-version-file: .test-deps/future-agi/fi-collector/go.mod + cache-dependency-path: .test-deps/future-agi/fi-collector/go.sum + - name: Build the real production converter adapter + working-directory: .test-deps/future-agi/fi-collector + run: | + go build -o "$RUNNER_TEMP/crewai-ingestion-check" "$GITHUB_WORKSPACE/scripts/crewai-ingestion-check/main.go" + echo "CREWAI_INGESTION_CHECK=$RUNNER_TEMP/crewai-ingestion-check" >> "$GITHUB_ENV" - name: Check page contracts run: node --test scripts/crewai-page.test.mjs - - name: Run native snippets with loopback networking only + - name: Run native snippets through Collector and production ingestion offline run: | TEST_PYTHON="$(command -v python)" TEST_HOME="$(mktemp -d)" sudo env TEST_PYTHON="$TEST_PYTHON" TEST_HOME="$TEST_HOME" \ - unshare --net sh -c 'ip link set lo up; env -i PATH=/usr/bin:/bin HOME="$TEST_HOME" "$TEST_PYTHON" -I -m pytest --noconftest --import-mode=importlib -q scripts/crewai-native.test.py' + CREWAI_COLLECTOR="$CREWAI_COLLECTOR" CREWAI_INGESTION_CHECK="$CREWAI_INGESTION_CHECK" \ + unshare --net sh -c 'ip link set lo up; env -i PATH=/usr/bin:/bin HOME="$TEST_HOME" CREWAI_COLLECTOR="$CREWAI_COLLECTOR" CREWAI_INGESTION_CHECK="$CREWAI_INGESTION_CHECK" "$TEST_PYTHON" -I -m pytest --noconftest --import-mode=importlib -q scripts/crewai-native.test.py' diff --git a/scripts/crewai-ingestion-check/main.go b/scripts/crewai-ingestion-check/main.go new file mode 100644 index 000000000..54b209f86 --- /dev/null +++ b/scripts/crewai-ingestion-check/main.go @@ -0,0 +1,34 @@ +// Test adapter for the production OTLP conversion entrypoint, not a copied mapper. +// Build from the pinned future-agi/fi-collector checkout (see crewai-docs.yml). +package main + +import ( + "encoding/json" + "os" + + "github.com/future-agi/future-agi/fi-collector/exporter/clickhouse25exporter" + "go.opentelemetry.io/collector/pdata/ptrace" +) + +func main() { + encoder := json.NewEncoder(os.Stdout) + for _, filename := range os.Args[1:] { + data, err := os.ReadFile(filename) + if err != nil { + panic(err) + } + traces, err := (&ptrace.ProtoUnmarshaler{}).UnmarshalTraces(data) + if err != nil { + panic(err) + } + rows, err := clickhouse25exporter.Convert(traces) + if err != nil { + panic(err) + } + for _, row := range rows { + if err := encoder.Encode(row); err != nil { + panic(err) + } + } + } +} diff --git a/scripts/crewai-native.test.py b/scripts/crewai-native.test.py index 697f99493..d88a08fef 100644 --- a/scripts/crewai-native.test.py +++ b/scripts/crewai-native.test.py @@ -6,12 +6,17 @@ import asyncio import errno +import gzip import json import os import re import socket +import subprocess import threading +import time from contextlib import contextmanager +from dataclasses import dataclass +from functools import partial from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from pathlib import Path from uuid import uuid4 @@ -45,6 +50,7 @@ class LocalServer: def __init__(self): self.spans = [] + self.payloads = [] self.resources = [] self.headers = [] self.prompts = [] @@ -54,7 +60,10 @@ def __init__(self): class Handler(BaseHTTPRequestHandler): def do_POST(self): body = self.rfile.read(int(self.headers["Content-Length"])) + if self.headers.get("Content-Encoding") == "gzip": + body = gzip.decompress(body) if self.path == "/tracer/v1/traces": + owner.payloads.append(body) request = ExportTraceServiceRequest.FromString(body) data = MessageToDict(request) owner.headers.append(dict(self.headers)) @@ -105,7 +114,12 @@ def do_POST(self): self.send_error(404) return self.send_response(status) - self.send_header("Content-Type", "application/json") + self.send_header( + "Content-Type", + "application/x-protobuf" + if self.path == "/tracer/v1/traces" + else "application/json", + ) self.send_header("Content-Length", str(len(response))) self.end_headers() self.wfile.write(response) @@ -131,24 +145,82 @@ def attrs(span): } +PAGE = Path(__file__).parent.parent / "src/pages/docs/integrations/traceai/crewai.mdx" + + +@contextmanager +def collector(server, tmp_path): + """Run the guide's actual pipeline, changing only network destinations. + + The binary and production-ingestion adapter are mandatory, not optional + skips. CI downloads the pinned public Collector and builds the adapter. + """ + with socket.socket() as reservation: + reservation.bind(("127.0.0.1", 0)) + port = reservation.getsockname()[1] + blocks = re.findall(r"```yaml\n(.*?)```", PAGE.read_text(), re.S) + assert len(blocks) == 1 + config = ( + blocks[0] + .replace("127.0.0.1:4318", f"127.0.0.1:{port}") + .replace( + "https://api.futureagi.com/tracer/v1/traces", + server.origin + "/tracer/v1/traces", + ) + ) + config_path = tmp_path / "crewai-collector.yaml" + config_path.write_text(config) + env = dict( + os.environ, FI_API_KEY="synthetic-fi-key", FI_SECRET_KEY="synthetic-fi-secret" + ) + args = [os.environ["CREWAI_COLLECTOR"], "--config=" + str(config_path)] + subprocess.run( + [args[0], "validate", *args[1:]], env=env, check=True, capture_output=True + ) + server.collector_endpoint = f"http://127.0.0.1:{port}/v1/traces" + log_path = tmp_path / "collector.log" + with log_path.open("w") as log: + # Disable only the Collector's own metrics listener to avoid port clashes. + process = subprocess.Popen( + [*args, "--set=service.telemetry.metrics.level=none"], + env=env, + stdout=log, + stderr=log, + ) + try: + deadline = time.monotonic() + 15 + while True: + assert process.poll() is None, log_path.read_text() + try: + with socket.create_connection(("127.0.0.1", port), timeout=0.1): + break + except OSError: + assert time.monotonic() < deadline, log_path.read_text() + time.sleep(0.05) + yield + finally: + if process.poll() is None: + process.terminate() + try: + process.wait(timeout=10) + except subprocess.TimeoutExpired: + process.kill() + process.wait(timeout=5) + + @pytest.fixture -def server(): +def server(tmp_path): value = LocalServer() try: - yield value + with collector(value, tmp_path): + yield value finally: value.close() @contextmanager def session(server): - exporter = OTLPSpanExporter( - endpoint=server.origin + "/tracer/v1/traces", - headers={ - "X-Api-Key": "synthetic-fi-key", - "X-Secret-Key": "synthetic-fi-secret", - }, - ) + exporter = OTLPSpanExporter(endpoint=server.collector_endpoint) with telemetry_session( str(uuid4()), "crewai_project", @@ -365,20 +437,17 @@ async def run_both(): def test_documented_python_snippets(server, monkeypatch): - page = ( - Path(__file__).parent.parent / "src/pages/docs/integrations/traceai/crewai.mdx" - ).read_text() - snippets = re.findall(r"```python\n(.*?)```", page, re.S) + snippets = re.findall(r"```python\n(.*?)```", PAGE.read_text(), re.S) assert len(snippets) == 2 - monkeypatch.setenv("FI_API_KEY", "synthetic-fi-key") - monkeypatch.setenv("FI_SECRET_KEY", "synthetic-fi-secret") + # Only the Collector needs Future AGI credentials. + monkeypatch.delenv("FI_API_KEY", raising=False) + monkeypatch.delenv("FI_SECRET_KEY", raising=False) monkeypatch.setenv("OPENAI_MODEL", "openai/gpt-4o-mini") monkeypatch.setenv("OPENAI_BASE_URL", server.origin + "/v1") - # The only code substitution is the collector destination. The documented - # credentials, Resource, native session and complete application run as-is. + # Substitute only the local Collector's ephemeral listening port. code = snippets[0].replace( - "https://api.futureagi.com/tracer/v1/traces", - server.origin + "/tracer/v1/traces", + "http://127.0.0.1:4318/v1/traces", + server.collector_endpoint, ) scope = {"__name__": __name__} exec(compile(code, "crewai_example.py", "exec"), scope) @@ -396,3 +465,101 @@ def test_documented_python_snippets(server, monkeypatch): "summary": "Distributed tracing connects the steps in an agent workflow." } assert_transport(server) + + +def test_configuration_only_credentials_do_not_leave_pipeline(server, monkeypatch): + def weather(city, *, api_key): + return f"Weather in {city}: clear." + + @dataclass + class CompletionCallback: + api_key: str + + def __call__(self, *args, **kwargs): + return None + + for name in ("FI_HIDE_INPUTS", "FI_HIDE_OUTPUTS", "FI_HIDE_ERROR_DETAILS"): + monkeypatch.setenv(name, "true") + canaries = ("synthetic-function-config-canary", "synthetic-callback-config-canary") + with session(server): + result = agent(server).llm.call( + "Write a useful answer", + tools=[ + { + "type": "function", + "function": { + "name": "weather", + "description": "Check weather", + "parameters": { + "type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"], + }, + }, + } + ], + available_functions={"weather": partial(weather, api_key=canaries[0])}, + callbacks=[CompletionCallback(api_key=canaries[1])], + ) + assert "Useful answer" in result + assert len(server.spans) == 1 + for canary in canaries: + assert canary not in json.dumps(server.prompts), "Not a model-input secret" + leaked = [ + canary for canary in canaries if canary.encode() in b"".join(server.payloads) + ] + assert not leaked, f"Configuration leaked in OTLP: {leaked}" + values = attrs(server.spans[0]) + assert "crewai.llm.available_functions" not in values + assert "crewai.llm.callbacks" not in values + assert values["gen_ai.request.model"] == "gpt-4o-mini" + assert_transport(server) + + +def test_native_lifecycle_production_ingestion(server, tmp_path): + class NestedFlow(Flow): + @start() + def execute(self): + writer = agent(server) + task = Task( + description="Write a useful answer", + expected_output="One sentence", + agent=writer, + ) + return Crew(agents=[writer], tasks=[task]).kickoff().raw + + with session(server): + assert "Useful answer" in NestedFlow().kickoff() + assert len(server.spans) == 6 + assert len({s["traceId"] for s in server.spans}) == 1 + files = [] + for index, payload in enumerate(server.payloads): + path = tmp_path / f"native-{index}.pb" + path.write_bytes(payload) + files.append(str(path)) + # Mandatory: no skip or Python reimplementation of the production converter. + result = subprocess.run( + [os.environ["CREWAI_INGESTION_CHECK"], *files], + capture_output=True, + text=True, + check=True, + ) + rows = [json.loads(line) for line in result.stdout.splitlines()] + assert len(rows) == 6 + expected = { + "invoke_workflow": "chain", + "execute_method": "chain", + "execute_task": "chain", + "invoke_agent": "agent", + "chat": "llm", + } + assert {row["gen_ai_operation"] for row in rows} == set(expected) + for row in rows: + assert row["observation_type"] == expected[row["gen_ai_operation"]], row + model = next(row for row in rows if row["observation_type"] == "llm") + assert model["model"] == "gpt-4o-mini" + assert model["provider"] == "openai" + assert model["prompt_tokens"] == 11 + assert model["completion_tokens"] == 5 + assert model["total_tokens"] == 16 + assert_transport(server) diff --git a/scripts/crewai-page.test.mjs b/scripts/crewai-page.test.mjs index a234fee8c..efa1c5679 100644 --- a/scripts/crewai-page.test.mjs +++ b/scripts/crewai-page.test.mjs @@ -10,9 +10,11 @@ test('CrewAI leads with the published native lifecycle route', () => { assert.match(native, /opentelemetry-exporter-otlp-proto-http/); assert.match(native, /from crewai\.telemetry\.tracing import telemetry_session/); assert.match(native, /with telemetry_session\(/); - assert.match(native, /"https:\/\/api\.futureagi\.com\/tracer\/v1\/traces"/); - assert.match(native, /"X-Api-Key": os\.environ\["FI_API_KEY"\]/); - assert.match(native, /"X-Secret-Key": os\.environ\["FI_SECRET_KEY"\]/); + assert.match(native, /traces_endpoint: https:\/\/api\.futureagi\.com\/tracer\/v1\/traces/); + assert.match(native, /X-Api-Key: \$\{env:FI_API_KEY\}/); + assert.match(native, /X-Secret-Key: \$\{env:FI_SECRET_KEY\}/); + assert.match(native, /OTLPSpanExporter\(endpoint="http:\/\/127\.0\.0\.1:4318\/v1\/traces"\)/); + assert.doesNotMatch(native, /endpoint="https:\/\/api\.futureagi\.com/); assert.match(native, /"project_name": "crewai_project"/); assert.match(native, /"project_type": "observe"/); assert.doesNotMatch(native, /CrewAIInstrumentor\(\)|class .*Exporter|def .*export/); @@ -26,6 +28,20 @@ test('native privacy and duplicate-span boundaries are actionable', () => { assert.match(native, /state.*error/s); }); +test('the required Collector filters configuration and assigns lifecycle types', () => { + assert.match(native, /Do not export native sessions directly to Future AGI/); + assert.match(native, /Collector Contrib 0\.164\.0/); + assert.match(native, /otelcol-contrib validate --config=crewai-collector\.yaml/); + assert.match(native, /error_mode: propagate/); + assert.match(native, /delete_key\(attributes, "crewai\.llm\.available_functions"\)/); + assert.match(native, /delete_key\(attributes, "crewai\.llm\.callbacks"\)/); + assert.match(native, /set\(attributes\["fi\.span\.kind"\], "agent"\).*"invoke_agent"/s); + assert.match(native, /set\(attributes\["fi\.span\.kind"\], "chain"\).*"invoke_workflow".*"execute_task".*"execute_method"/s); + assert.match(native, /processors: \[transform\/crewai\]/); + assert.match(native, /Keep the local receiver private/); + assert.match(native, /FI_HIDE_ERROR_DETAILS/); +}); + test('existing package users retain their supported route and scope', () => { assert.match(legacy, /traceAI-crewai>=0\.1\.10/); assert.match(legacy, /Flow.*standalone.*model/s); diff --git a/src/pages/docs/integrations/traceai/crewai.mdx b/src/pages/docs/integrations/traceai/crewai.mdx index 80ae42b05..e4e63356a 100644 --- a/src/pages/docs/integrations/traceai/crewai.mdx +++ b/src/pages/docs/integrations/traceai/crewai.mdx @@ -1,9 +1,9 @@ --- title: "CrewAI tracing" -description: "Send CrewAI's native crew, task, agent, Flow and model-call spans to Future AGI over OpenTelemetry." +description: "Send CrewAI's native lifecycle spans to Future AGI through an OpenTelemetry Collector with configuration filtering and observation types." --- -Trace crews, standalone agents, Flows and model calls in **Observe** using CrewAI's native OpenTelemetry session. +Trace crews, standalone agents, Flows and model calls in **Observe** using CrewAI's native OpenTelemetry session and a local Collector. ## Install @@ -13,6 +13,8 @@ Use Python 3.10–3.13 and CrewAI 1.15.33 or newer. pip install 'crewai>=1.15.33,<2' opentelemetry-exporter-otlp-proto-http ``` +Install [OpenTelemetry Collector Contrib 0.164.0](https://github.com/open-telemetry/opentelemetry-collector-releases/releases/tag/v0.164.0) for your operating system and put `otelcol-contrib` on your `PATH`. The Contrib distribution includes the transform processor used below. + This route uses CrewAI's event lifecycle directly. You do not need `traceAI-crewai` or a copied tracing helper. ## Configure credentials and destinations @@ -30,13 +32,67 @@ export CREWAI_DISABLE_TELEMETRY=true export CREWAI_TRACING_ENABLED=false ``` -The explicit session below still sends spans to Future AGI. Do not enable another CrewAI or model-client instrumentor for the same execution: native sessions already create model-call spans, and combining routes can duplicate them. +The explicit session below still exports spans. Do not enable another CrewAI or model-client instrumentor for the same execution: native sessions already create model-call spans, and combining routes can duplicate them. + +## Start the local Collector + +**Do not export native sessions directly to Future AGI.** CrewAI serializes function registries and callbacks into span attributes, including credentials held by partial functions and callable objects. The required Collector configuration below removes `crewai.llm.available_functions` and `crewai.llm.callbacks` before export. It also maps agents to **agent** observations and crews, tasks, Flows and methods to **chain** observations; model calls remain **llm** observations. + +Save this as `crewai-collector.yaml`. Use this receiver only for CrewAI traces. It listens on loopback, so run the Collector alongside the Python process on the same host. Future AGI credentials are read by the Collector, not attached to the application's local exporter. + +```yaml +receivers: + otlp: + protocols: + http: + endpoint: 127.0.0.1:4318 + +processors: + transform/crewai: + error_mode: propagate + trace_statements: + - context: span + statements: + - delete_key(attributes, "crewai.llm.available_functions") + - delete_key(attributes, "crewai.llm.callbacks") + - >- + set(attributes["fi.span.kind"], "agent") + where attributes["gen_ai.operation.name"] == "invoke_agent" + - >- + set(attributes["fi.span.kind"], "chain") + where attributes["gen_ai.operation.name"] == "invoke_workflow" + or attributes["gen_ai.operation.name"] == "execute_task" + or attributes["gen_ai.operation.name"] == "execute_method" + +exporters: + otlphttp/futureagi: + traces_endpoint: https://api.futureagi.com/tracer/v1/traces + headers: + X-Api-Key: ${env:FI_API_KEY} + X-Secret-Key: ${env:FI_SECRET_KEY} + sending_queue: + enabled: false + +service: + pipelines: + traces: + receivers: [otlp] + processors: [transform/crewai] + exporters: [otlphttp/futureagi] +``` -**Content capture:** native sessions export application inputs, outputs, Flow state and error details. Keep credentials and sensitive data out of these fields, including tool results and exception messages. `FI_HIDE_INPUTS` and `FI_HIDE_OUTPUTS` do not apply to CrewAI's native provider. If you require content filtering, send through an OpenTelemetry Collector with your organization's redaction policy before forwarding to Future AGI; do not assume the traceAI privacy settings cover this route. +In a terminal with `FI_API_KEY` and `FI_SECRET_KEY` set, start the Collector and leave it running: + +```bash +otelcol-contrib validate --config=crewai-collector.yaml +otelcol-contrib --config=crewai-collector.yaml +``` + +**Content capture:** this configuration removes runtime function and callback configuration, not application content. Native sessions still export inputs, outputs, tool definitions/results, Flow state and error details. Keep credentials and sensitive data out of that content and add your organization's redaction policy to the Collector if needed. `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS` and `FI_HIDE_ERROR_DETAILS` do not apply to CrewAI's native provider. Keep the local receiver private; it receives the unfiltered spans. Do not add an exporter or pipeline that bypasses the transform processor. ## Run a traced crew -Save this as `crewai_example.py`. The OpenTelemetry exporter sends OTLP/HTTP protobuf to Future AGI; the resource selects your Observe project. +Save this as `crewai_example.py` and run it in another terminal with the CrewAI and OpenAI environment variables set. The application sends OTLP/HTTP protobuf to the local Collector; only the filtered, normalized spans are forwarded to Future AGI. The resource selects your Observe project. ```python import os @@ -47,13 +103,7 @@ from crewai.telemetry.tracing import telemetry_session from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.resources import Resource -exporter = OTLPSpanExporter( - endpoint="https://api.futureagi.com/tracer/v1/traces", - headers={ - "X-Api-Key": os.environ["FI_API_KEY"], - "X-Secret-Key": os.environ["FI_SECRET_KEY"], - }, -) +exporter = OTLPSpanExporter(endpoint="http://127.0.0.1:4318/v1/traces") resource = Resource({ "service.name": "crewai-app", "project_name": "crewai_project", @@ -131,6 +181,7 @@ CrewAI 0.41.1 has no native telemetry opt-out: upgrade CrewAI if you need to dis ## Troubleshooting -- **No spans arrive:** keep execution inside `telemetry_session`, let the context exit, and check that both Future AGI headers are set. Use the full `/tracer/v1/traces` HTTP endpoint, not a gRPC endpoint. +- **No spans arrive:** keep execution inside `telemetry_session`, let the context exit, and check the Collector's logs. The application must reach `http://127.0.0.1:4318/v1/traces`; the Collector must have both Future AGI credentials and use the full `/tracer/v1/traces` HTTPS endpoint. +- **Agent or chain filters miss spans:** check that the `transform/crewai` processor is present in the traces pipeline. Do not point the Python exporter directly at Future AGI to bypass a Collector error. - **Duplicate model spans:** remove other CrewAI and model-client instrumentors from this execution and disable CrewAI-hosted tracing with `CREWAI_TRACING_ENABLED=false`. - **Native session import fails:** upgrade CrewAI to the version range in the install command and restart the Python process.