Skip to content

Commit 14c90d5

Browse files
JWinermaSplunkJWinermaSplunk
committed
initial commit
1 parent 08804c8 commit 14c90d5

File tree

11 files changed

+159
-0
lines changed

11 files changed

+159
-0
lines changed

‎.chloggen/retrieval-span-support.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Use this changelog template to create an entry for release notes.
2+
#
3+
# If your change doesn't affect end users you should instead start
4+
# your pull request title with [chore] or use the "Skip Changelog" label.
5+
6+
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
7+
change_type: 'new_component'
8+
9+
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
10+
component: gen-ai
11+
12+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
13+
note: Add retrieval span support to the gen-ai-spans semantic conventions.
14+
15+
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
16+
# The values here must be integers.
17+
issues: [2907]
18+
19+
# (Optional) One or more lines of additional information to render under the primary note.
20+
# These lines will be padded with 2 spaces and then inserted directly into the document.
21+
# Use pipe (|) for multiline entries.
22+
subtext:

‎docs/gen-ai/aws-bedrock.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ populating this attribute.
222222
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
223223
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
224224
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
225+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
225226
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
226227

227228
---

‎docs/gen-ai/azure-ai-inference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ populating this attribute.
223223
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
224224
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
225225
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
226+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
226227
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
227228

228229
---

‎docs/gen-ai/gen-ai-agent-spans.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ Instrumentations SHOULD document the list of errors they report.
132132
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
133133
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
134134
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
135+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
135136
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
136137

137138
---
@@ -362,6 +363,7 @@ populating this attribute.
362363
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
363364
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
364365
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
366+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
365367
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
366368

367369
---

‎docs/gen-ai/gen-ai-events.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,7 @@ populating this attribute.
203203
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
204204
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
205205
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
206+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
206207
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
207208

208209
---

‎docs/gen-ai/gen-ai-metrics.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
125125
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
126126
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
127127
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
128+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
128129
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
129130

130131
---
@@ -245,6 +246,7 @@ Instrumentations SHOULD document the list of errors they report.
245246
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
246247
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
247248
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
249+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
248250
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
249251

250252
---
@@ -363,6 +365,7 @@ Instrumentations SHOULD document the list of errors they report.
363365
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
364366
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
365367
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
368+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
366369
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
367370

368371
---
@@ -468,6 +471,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
468471
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
469472
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
470473
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
474+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
471475
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
472476

473477
---
@@ -572,6 +576,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
572576
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
573577
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
574578
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
579+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
575580
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
576581

577582
---

‎docs/gen-ai/gen-ai-spans.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ linkTitle: Spans
1111
- [Spans](#spans)
1212
- [Inference](#inference)
1313
- [Embeddings](#embeddings)
14+
- [Retrievals](#retrievals)
1415
- [Execute tool span](#execute-tool-span)
1516
- [Capturing instructions, inputs, and outputs](#capturing-instructions-inputs-and-outputs)
1617
- [Full (buffered) content](#full-buffered-content)
@@ -235,6 +236,7 @@ populating this attribute.
235236
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
236237
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
237238
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
239+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
238240
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
239241

240242
---
@@ -345,6 +347,78 @@ Instrumentations SHOULD document the list of errors they report.
345347
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
346348
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
347349
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
350+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
351+
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
352+
353+
<!-- markdownlint-restore -->
354+
<!-- prettier-ignore-end -->
355+
<!-- END AUTOGENERATED TEXT -->
356+
<!-- endsemconv -->
357+
358+
### Retrievals
359+
360+
<!-- semconv span.gen_ai.retrieval.client -->
361+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
362+
<!-- see templates/registry/markdown/snippet.md.j2 -->
363+
<!-- prettier-ignore-start -->
364+
<!-- markdownlint-capture -->
365+
<!-- markdownlint-disable -->
366+
367+
**Status:** ![Development](https://img.shields.io/badge/-development-blue)
368+
369+
Describes GenAI Retrieval Span - where relevant information or context is stored in a vector database or search system to be passed to a language model at a later time.
370+
The `gen_ai.operation.name` SHOULD be `retrieval`.
371+
**Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
372+
373+
**Span kind** SHOULD be `CLIENT`.
374+
375+
**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.
376+
377+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
378+
|---|---|---|---|---|---|
379+
| [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
380+
| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
381+
| [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | `Conditionally Required` If available. | ![Development](https://img.shields.io/badge/-development-blue) |
382+
| [`server.port`](/docs/registry/attributes/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
383+
| [`gen_ai.retrieval.documents_retrieved`](/docs/registry/attributes/gen-ai.md) | int | The number of documents retrieved. | `5`; `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
384+
| [`gen_ai.retrieval.top_k`](/docs/registry/attributes/gen-ai.md) | int | The number of documents to retrieve. | `5`; `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
385+
| [`gen_ai.retrieval.type`](/docs/registry/attributes/gen-ai.md) | string | The type of retrieval being performed. | `similarity`; `hybrid` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
386+
| [`gen_ai.retrieval.vector_store`](/docs/registry/attributes/gen-ai.md) | string | The vector store being used for retrieval. | `faiss`; `pinecone` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
387+
| [`server.address`](/docs/registry/attributes/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
388+
389+
**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
390+
391+
**[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
392+
the canonical name of exception that occurred, or another low-cardinality error identifier.
393+
Instrumentations SHOULD document the list of errors they report.
394+
395+
**[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.
396+
397+
**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
398+
399+
**[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
400+
401+
---
402+
403+
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
404+
405+
| Value | Description | Stability |
406+
|---|---|---|
407+
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
408+
409+
---
410+
411+
`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
412+
413+
| Value | Description | Stability |
414+
|---|---|---|
415+
| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) |
416+
| `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
417+
| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) |
418+
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
419+
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
420+
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
421+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
348422
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
349423

350424
<!-- markdownlint-restore -->
@@ -435,6 +509,7 @@ deserialize it to an object. When recorded on spans, it MAY be recorded as a JSO
435509
| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) |
436510
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
437511
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
512+
| `retrieval` | Retrieval operation such as [OpenAI Retrieval API](https://platform.openai.com/docs/guides/retrieval) | ![Development](https://img.shields.io/badge/-development-blue) |
438513
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
439514

440515
<!-- markdownlint-restore -->

0 commit comments

Comments
 (0)