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
1 change: 1 addition & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import './azure-openai-java.test.mjs';
import './langsmith-page.test.mjs';
import './vercel-platform-page.test.mjs';
import './scalekit-page.test.mjs';
import './parallel-page.test.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
Expand Down
104 changes: 104 additions & 0 deletions scripts/parallel-page.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import { spawnSync } from 'node:child_process';
import { integrations } from '../src/lib/integrations.mjs';

const page = fs.readFileSync(new URL('../src/pages/docs/integrations/traceai/parallel.mdx', import.meta.url), 'utf8');

test('Parallel guide uses released packages and the shared integration catalog', () => {
const entry = integrations.find(item => item.id === 'parallel');
assert.equal(entry?.href, '/docs/integrations/traceai/parallel');
assert.equal(entry?.category, 'frameworks');
assert.equal(entry?.method, 'traceAI SDK');
for (const pin of ['traceAI-parallel==0.1.1', 'fi-instrumentation-otel==1.2.3', 'parallel-web==1.3.5']) {
assert.ok(page.includes(pin), pin);
}
assert.match(page, /Task runs, task groups, FindAll and Monitor are not traced/);
assert.match(page, /Open \*\*Observe\*\*/);
assert.doesNotMatch(page, /Live vendor verification|Tested versions|verified live|STANDIN|\bAlpha\b|2026-10-17/i);
});

test('Parallel guide preserves privacy controls and raw-response limitations', () => {
for (const flag of ['FI_HIDE_INPUTS', 'FI_HIDE_OUTPUTS', 'FI_HIDE_ERROR_DETAILS']) {
assert.ok(page.includes(`export ${flag}=true`), flag);
}
assert.match(page, /before initializing the instrumentor/);
assert.match(page, /verbatim matches only, not escaped or truncated copies/);
assert.match(page, /response bodies are not parsed for result counts or IDs/);
assert.match(page, /streaming spans end when response headers arrive/);
});

test('Parallel example skips extraction for empty results and flushes on success or errors', () => {
const example = page.match(/```python\n([\s\S]*?)\n```/)?.[1];
assert.ok(example, 'Keep one complete runnable Python example');
// Execute the documented control flow with stub clients, never vendor calls.
const harness = String.raw`
import contextlib
import io
import sys
import types

source = sys.stdin.read()
code = compile(source, 'parallel_example.py', 'exec')

for scenario in ('empty', 'hit', 'search_error', 'extract_error'):
calls = []
provider = types.SimpleNamespace(force_flush=lambda: calls.append('flush'))
def register(**kwargs):
assert kwargs == dict(project_type='observe', project_name='parallel-search')
calls.append('register')
return provider
class Instrumentor:
def instrument(self, *, tracer_provider):
assert tracer_provider is provider
calls.append('instrument')
class Parallel:
def __enter__(self):
assert calls == ['register', 'instrument']
return self
def __exit__(self, *args):
calls.append('close')
def search(self, *, search_queries, mode):
assert search_queries and mode == 'turbo'
calls.append('search')
if scenario == 'search_error':
raise RuntimeError('search failed')
results = [] if scenario == 'empty' else [types.SimpleNamespace(url='https://example.com')]
return types.SimpleNamespace(results=results, session_id='example-session')
def extract(self, *, urls, session_id):
assert urls == ['https://example.com']
assert session_id == 'example-session'
calls.append('extract')
if scenario == 'extract_error':
raise RuntimeError('extract failed')
return types.SimpleNamespace(results=[object()])
modules = {
'fi_instrumentation': dict(register=register),
'fi_instrumentation.fi_types': dict(ProjectType=types.SimpleNamespace(OBSERVE='observe')),
'traceai_parallel': dict(ParallelInstrumentor=Instrumentor),
'parallel': dict(Parallel=Parallel),
}
for name, attrs in modules.items():
module = types.ModuleType(name)
module.__dict__.update(attrs)
sys.modules[name] = module
output = io.StringIO()
raised = None
with contextlib.redirect_stdout(output):
try:
exec(code, {})
except RuntimeError as error:
raised = str(error)
expected_error = scenario.replace('_error', ' failed') if scenario.endswith('_error') else None
assert raised == expected_error, (scenario, raised)
operations = ['search'] if scenario in ('empty', 'search_error') else ['search', 'extract']
assert calls == ['register', 'instrument', *operations, 'close', 'flush'], (scenario, calls)
if scenario == 'empty':
assert 'No search results' in output.getvalue()
elif scenario == 'hit':
assert 'Extracted 1 page(s).' in output.getvalue()
`;
const result = spawnSync('python3', ['-I', '-c', harness], { input: example, encoding: 'utf8' });
assert.equal(result.status, 0, result.error?.message || result.stdout + result.stderr);
});
1 change: 1 addition & 0 deletions src/lib/integrations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ export const integrations = [
{ id: 'novita-ai', name: 'Novita AI', href: '/docs/integrations/providers/novita-ai', category: 'providers', summary: 'Trace Novita chat completions from your Python app.', method: 'OpenAI client', logo: 'novita' },
{ id: 'litellm-sdk', name: 'LiteLLM SDK', href: '/docs/integrations/traceai/litellm', category: 'frameworks', summary: 'Instrument LiteLLM calls in your Python application.', method: 'traceAI SDK', logo: 'litellm', aliases: ['traceAI-litellm', 'client'] },

{ id: 'parallel', name: 'Parallel', href: '/docs/integrations/traceai/parallel', category: 'frameworks', summary: 'Trace Python Search and Extract calls, result counts and errors.', method: 'traceAI SDK', logo: 'generic-framework' },
{ id: 'langchain', name: 'LangChain', href: '/docs/integrations/traceai/langchain', category: 'frameworks', summary: 'Trace chains, retrievers, tools and model calls.', method: 'traceAI SDK', logo: 'langchain' },
{ id: 'langgraph', name: 'LangGraph', href: '/docs/integrations/traceai/langgraph', category: 'frameworks', summary: 'Follow agent graph execution and tool calls.', method: 'traceAI SDK', logo: 'langgraph' },
{ id: 'llamaindex', name: 'LlamaIndex', href: '/docs/integrations/traceai/llamaindex', category: 'frameworks', summary: 'Trace retrieval and generation in RAG applications.', method: 'traceAI SDK', logo: 'llamaindex', aliases: ['RAG'] },
Expand Down
100 changes: 100 additions & 0 deletions src/pages/docs/integrations/traceai/parallel.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
title: "Parallel Integration with Future AGI for Search and Extract Tracing"
description: "Trace Parallel Search and Extract calls in Future AGI with the traceAI-parallel instrumentor for the parallel-web client."
---

Trace Parallel Search and Extract calls in Future AGI with the maintained `traceAI-parallel` package. Each call records its duration, result counts and errors. This integration covers the Python client; Task runs, task groups, FindAll and Monitor are not traced.

## Install

Use Python 3.10–3.13 and a Parallel API key. Install the instrumentor, tracing SDK and client:

```bash
pip install 'traceAI-parallel==0.1.1' 'fi-instrumentation-otel==1.2.3' 'parallel-web==1.3.5'
```

The instrumentor requires `parallel-web>=1.0.1,<2`.

## Configure credentials and privacy

Set your Parallel and [Future AGI API keys](/docs/admin-settings/api-keys) in the environment that runs your application:

```bash
export PARALLEL_API_KEY="your-parallel-api-key"
export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"
```

Search queries are recorded by default. To hide input content, warning messages and error details, set these variables **before initializing the instrumentor**:

```bash
export FI_HIDE_INPUTS=true
export FI_HIDE_OUTPUTS=true
export FI_HIDE_ERROR_DETAILS=true
```

These settings preserve counts, mode, IDs, error status and exception types. Requested URLs and objectives are not recorded as attributes unless you enable `capture_urls=True` or `capture_objective=True` on `instrument()`; `FI_HIDE_INPUTS=true` overrides both options.

Without these privacy settings, error and warning text can contain request content. Key and input redaction replaces verbatim matches only, not escaped or truncated copies. Keep sensitive content out of requests or use the settings above. See [TraceConfig](/docs/sdk/tracing/trace-config) for additional controls.

## Run a search and extract

Save this as `parallel_example.py`. Register tracing and instrument the client before making API calls:

```python
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from parallel import Parallel
from traceai_parallel import ParallelInstrumentor

trace_provider = register(
project_type=ProjectType.OBSERVE,
project_name="parallel-search",
)
ParallelInstrumentor().instrument(tracer_provider=trace_provider)

try:
with Parallel() as client: # reads PARALLEL_API_KEY
result = client.search(
search_queries=["OpenTelemetry distributed tracing"], mode="turbo"
)
if result.results:
extracted = client.extract(
urls=[result.results[0].url], session_id=result.session_id
)
print(f"Extracted {len(extracted.results)} page(s).")
else:
print("No search results; try a more specific query.")
finally:
trace_provider.force_flush()
```

```bash
python parallel_example.py
```

Open **Observe** in Future AGI and select **parallel-search**. Inspect `parallel.search` and, when the search returns a result, `parallel.extract`. Calls made under an active span become its children; otherwise each call starts a separate trace.

## What is captured

Both `Parallel` and `AsyncParallel` are instrumented. Retries within a client call stay in the same span.

| Call | Span name | Span kind |
|---|---|---|
| `search` | `parallel.search` | `RETRIEVER` |
| `extract` | `parallel.extract` | `TOOL` |

Spans include query or URL counts, result counts, failed-URL counts for extraction, search/extract/session IDs, and the search mode when supplied. Search queries are stored in `gen_ai.retrieval.query` and `input.value`, capped at 1 KB, unless inputs are hidden. Usage SKU names and counts are recorded when returned; they are not token counts or monetary costs.

The instrumentor does not capture result excerpts, titles, result URLs or page text. Response warnings become `parallel.warning` events. API errors set the span status to `ERROR` and propagate unchanged to your code. With error details enabled, exception events contain an exception summary, not traceback frames. An async cancellation sets `parallel.cancelled=true`.

Calls through `copy()` and `with_options()` are also traced. For `with_raw_response` and `with_streaming_response`, access those wrappers only after calling `instrument()`. Their response bodies are not parsed for result counts or IDs; streaming spans end when response headers arrive, not when the body finishes reading.

## Troubleshooting

- **No spans appear.** Check `FI_API_KEY` and `FI_SECRET_KEY`, initialize the instrumentor before API calls, and flush the provider before a short-lived process exits.
- **No extract span appears.** An empty search result skips extraction. Try a different query and inspect the search span's result count.
- **`instrument()` reports a dependency conflict.** Use a `parallel-web` version within `>=1.0.1,<2`.
- **`ParallelError` when creating the client.** Set `PARALLEL_API_KEY`. Client initialization fails before a traced API call when the key is missing.

For Model Context Protocol traffic, use the [MCP integration](/docs/integrations/traceai/mcp). An agent framework's tool span describes its tool invocation; this instrumentor adds the underlying Parallel API span beneath it when the framework keeps that span active.
Loading