Skip to content

Commit 11192af

Browse files
mikeldkingmikeldking
committed
add more docs
1 parent 761d974 commit 11192af

File tree

2 files changed

+335
-0
lines changed

2 files changed

+335
-0
lines changed

‎js/packages/openinference-core/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,187 @@ span.setAttributes(contextAttributes);
8989
span.end();
9090
```
9191
92+
## Tracing Helpers
93+
94+
This package provides convenient helpers to instrument your functions, agents, and LLM operations with OpenInference spans.
95+
96+
### Function Tracing
97+
98+
**`withSpan`** - Wraps any function (sync or async) with OpenTelemetry tracing:
99+
100+
```typescript
101+
import { withSpan } from "@arizeai/openinference-core";
102+
import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
103+
104+
const processUserQuery = async (query: string) => {
105+
// Your business logic here
106+
const response = await fetch(`/api/process?q=${query}`);
107+
return response.json();
108+
};
109+
110+
const tracedProcess = withSpan(processUserQuery, {
111+
name: "user-query-processor",
112+
kind: OpenInferenceSpanKind.CHAIN,
113+
});
114+
```
115+
116+
**`traceChain`** - Convenience wrapper for tracing workflow sequences:
117+
118+
```typescript
119+
import { traceChain } from "@arizeai/openinference-core";
120+
121+
const ragPipeline = async (question: string) => {
122+
const documents = await retrieveDocuments(question);
123+
const context = documents.map((d) => d.content).join("\n");
124+
const answer = await generateAnswer(question, context);
125+
return answer;
126+
};
127+
128+
const tracedRag = traceChain(ragPipeline, { name: "rag-pipeline" });
129+
```
130+
131+
**`traceAgent`** - Convenience wrapper for tracing autonomous agents:
132+
133+
```typescript
134+
import { traceAgent } from "@arizeai/openinference-core";
135+
136+
const simpleAgent = async (question: string) => {
137+
// Agent logic that may call tools, make decisions, etc.
138+
const documents = await retrieveDocuments(question);
139+
const analysis = await analyzeContext(question, documents);
140+
return await executePlan(analysis);
141+
};
142+
143+
const tracedAgent = traceAgent(simpleAgent, { name: "qa-agent" });
144+
```
145+
146+
**`traceTool`** - Convenience wrapper for tracing external tools:
147+
148+
```typescript
149+
import { traceTool } from "@arizeai/openinference-core";
150+
151+
const weatherTool = async (city: string) => {
152+
const response = await fetch(`https://api.weather.com/v1/${city}`);
153+
return response.json();
154+
};
155+
156+
const tracedWeatherTool = traceTool(weatherTool, { name: "weather-api" });
157+
```
158+
159+
### Decorators
160+
161+
**`@observe`** - Decorator for automatically tracing class methods:
162+
163+
```typescript
164+
import { observe } from "@arizeai/openinference-core";
165+
166+
class ChatService {
167+
@observe({ kind: "chain" })
168+
async processMessage(message: string) {
169+
// Your method implementation
170+
return `Processed: ${message}`;
171+
}
172+
173+
@observe({ name: "llm-call", kind: "llm" })
174+
async callLLM(prompt: string) {
175+
// LLM invocation
176+
return await llmClient.generate(prompt);
177+
}
178+
}
179+
```
180+
181+
### Attribute Helpers
182+
183+
**`getLLMAttributes`** - Generate attributes for LLM operations:
184+
185+
```typescript
186+
import { getLLMAttributes } from "@arizeai/openinference-core";
187+
import { trace } from "@opentelemetry/api";
188+
189+
const tracer = trace.getTracer("llm-service");
190+
191+
tracer.startActiveSpan("llm-inference", (span) => {
192+
const attributes = getLLMAttributes({
193+
provider: "openai",
194+
modelName: "gpt-4",
195+
inputMessages: [{ role: "user", content: "What is AI?" }],
196+
outputMessages: [{ role: "assistant", content: "AI is..." }],
197+
tokenCount: { prompt: 10, completion: 50, total: 60 },
198+
});
199+
span.setAttributes(attributes);
200+
span.end();
201+
});
202+
```
203+
204+
**`getEmbeddingAttributes`** - Generate attributes for embedding operations:
205+
206+
```typescript
207+
import { getEmbeddingAttributes } from "@arizeai/openinference-core";
208+
import { trace } from "@opentelemetry/api";
209+
210+
const tracer = trace.getTracer("embedding-service");
211+
212+
tracer.startActiveSpan("generate-embeddings", (span) => {
213+
const attributes = getEmbeddingAttributes({
214+
modelName: "text-embedding-ada-002",
215+
embeddings: [
216+
{ text: "The quick brown fox", vector: [0.1, 0.2, 0.3, ...] },
217+
{ text: "jumps over the lazy dog", vector: [0.4, 0.5, 0.6, ...] },
218+
],
219+
});
220+
span.setAttributes(attributes);
221+
span.end();
222+
});
223+
```
224+
225+
**`getRetrieverAttributes`** - Generate attributes for document retrieval:
226+
227+
```typescript
228+
import { getRetrieverAttributes } from "@arizeai/openinference-core";
229+
import { trace } from "@opentelemetry/api";
230+
231+
const tracer = trace.getTracer("retriever-service");
232+
233+
async function retrieveDocuments(query: string) {
234+
return tracer.startActiveSpan("retrieve-documents", async (span) => {
235+
const documents = await vectorStore.similaritySearch(query, 5);
236+
const attributes = getRetrieverAttributes({
237+
documents: documents.map((doc) => ({
238+
content: doc.pageContent,
239+
id: doc.metadata.id,
240+
score: doc.score,
241+
metadata: doc.metadata,
242+
})),
243+
});
244+
span.setAttributes(attributes);
245+
span.end();
246+
return documents;
247+
});
248+
}
249+
```
250+
251+
**`getToolAttributes`** - Generate attributes for tool definitions:
252+
253+
```typescript
254+
import { getToolAttributes } from "@arizeai/openinference-core";
255+
import { trace } from "@opentelemetry/api";
256+
257+
const tracer = trace.getTracer("tool-service");
258+
259+
tracer.startActiveSpan("define-tool", (span) => {
260+
const attributes = getToolAttributes({
261+
name: "search_web",
262+
description: "Search the web for information",
263+
parameters: {
264+
query: { type: "string", description: "The search query" },
265+
maxResults: { type: "number", description: "Maximum results to return" },
266+
},
267+
});
268+
span.setAttributes(attributes);
269+
span.end();
270+
});
271+
```
272+
92273
## Trace Config
93274
94275
This package also provides support for controlling settings like data privacy and payload sizes. For instance, you may want to keep sensitive information from being logged for security reasons, or you may want to limit the size of the base64 encoded images logged to reduced payload size.

‎js/packages/openinference-core/src/helpers/README.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# OpenInference Core Helpers
2+
3+
This directory contains helper utilities for instrumenting and tracing LLM applications with OpenInference. These helpers provide high-level abstractions for creating spans, processing attributes, and managing tracers.
4+
5+
## Core Areas
6+
7+
### Function Tracing
8+
9+
Core utilities for automatically tracing function execution. See [withSpan](withSpan.ts) and [wrappers](wrappers.ts) for implementation details.
10+
11+
**`withSpan`** - Wraps any function (sync or async) with OpenTelemetry tracing, automatically creating spans for execution monitoring:
12+
13+
```typescript
14+
import { withSpan } from "@arizeai/openinference-core";
15+
import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
16+
17+
const fetchData = async (url: string) => {
18+
const response = await fetch(url);
19+
return response.json();
20+
};
21+
22+
const tracedFetch = withSpan(fetchData, {
23+
name: "api-request",
24+
kind: OpenInferenceSpanKind.LLM,
25+
});
26+
```
27+
28+
**`traceChain`** - Convenience wrapper for tracing workflow sequences (CHAIN span kind):
29+
30+
```typescript
31+
import { traceChain } from "@arizeai/openinference-core";
32+
33+
const processData = (data: any[]) => {
34+
return data.map((item) => transform(item)).filter((item) => validate(item));
35+
};
36+
37+
const tracedProcess = traceChain(processData, { name: "data-pipeline" });
38+
```
39+
40+
**`traceAgent`** - Convenience wrapper for tracing agents (AGENT span kind):
41+
42+
```typescript
43+
import { traceAgent } from "@arizeai/openinference-core";
44+
45+
const makeDecision = async (context: Record<string, unknown>) => {
46+
const analysis = await analyzeContext(context);
47+
return await executePlan(analysis);
48+
};
49+
50+
const tracedAgent = traceAgent(makeDecision, { name: "decision-agent" });
51+
```
52+
53+
**`traceTool`** - Convenience wrapper for tracing external tools (TOOL span kind):
54+
55+
```typescript
56+
import { traceTool } from "@arizeai/openinference-core";
57+
58+
const fetchWeather = async (city: string) => {
59+
const response = await fetch(`/api/weather?city=${city}`);
60+
return response.json();
61+
};
62+
63+
const tracedWeatherTool = traceTool(fetchWeather, { name: "weather-api" });
64+
```
65+
66+
### Decorators
67+
68+
Class method decoration for automatic tracing. See [decorators](decorators.ts) for implementation details.
69+
70+
**`@observe`** - Decorator factory for tracing class methods:
71+
72+
```typescript
73+
import { observe } from "@arizeai/openinference-core";
74+
75+
class MyService {
76+
@observe({ kind: "chain" })
77+
async processData(input: string) {
78+
// Method implementation
79+
return `processed: ${input}`;
80+
}
81+
}
82+
```
83+
84+
### Attribute Helpers
85+
86+
Utilities for converting data structures into OpenTelemetry attributes. See [attributeHelpers](attributeHelpers.ts) for implementation details.
87+
88+
**Input/Output Processing** - Convert function arguments and return values to standardized span attributes:
89+
90+
```typescript
91+
import {
92+
defaultProcessInput,
93+
defaultProcessOutput,
94+
} from "@arizeai/openinference-core";
95+
96+
// Process input arguments
97+
const inputAttrs = defaultProcessInput("hello", { key: "value" });
98+
99+
// Process output result
100+
const outputAttrs = defaultProcessOutput({ status: "success" });
101+
```
102+
103+
**LLM Attributes** - Generate attributes for LLM operations:
104+
105+
```typescript
106+
import { getLLMAttributes } from "@arizeai/openinference-core";
107+
108+
const attrs = getLLMAttributes({
109+
provider: "openai",
110+
modelName: "gpt-4",
111+
inputMessages: [{ role: "user", content: "Hello" }],
112+
outputMessages: [{ role: "assistant", content: "Hi there!" }],
113+
tokenCount: { prompt: 10, completion: 5, total: 15 },
114+
});
115+
```
116+
117+
**Embedding Attributes** - Generate attributes for embedding operations:
118+
119+
```typescript
120+
import { getEmbeddingAttributes } from "@arizeai/openinference-core";
121+
122+
const attrs = getEmbeddingAttributes({
123+
modelName: "text-embedding-ada-002",
124+
embeddings: [
125+
{ text: "hello world", vector: [0.1, 0.2, 0.3] },
126+
{ text: "goodbye", vector: [0.4, 0.5, 0.6] },
127+
],
128+
});
129+
```
130+
131+
**Retriever Attributes** - Generate attributes for document retrieval:
132+
133+
```typescript
134+
import { getRetrieverAttributes } from "@arizeai/openinference-core";
135+
136+
const attrs = getRetrieverAttributes({
137+
documents: [
138+
{ content: "Document 1", id: "doc1", score: 0.95 },
139+
{ content: "Document 2", id: "doc2", metadata: { source: "web" } },
140+
],
141+
});
142+
```
143+
144+
**Tool Attributes** - Generate attributes for tool definitions:
145+
146+
```typescript
147+
import { getToolAttributes } from "@arizeai/openinference-core";
148+
149+
const attrs = getToolAttributes({
150+
name: "search_tool",
151+
description: "Search for information",
152+
parameters: { query: { type: "string" } },
153+
});
154+
```

0 commit comments

Comments
 (0)