keithchambers

Semantic Conventions

Table of Contents

1. Resource
2. Agent Span Kind
3. LLM Span Kind
4. Tool Span Kind
5. Chain Span Kind
6. Glossary

keithchambers

Data Schema for Agentic AI Application Observability

Version: 1.1  Date: May 22 2025

1. Overview

This document outlines the data schema for observing agentic AI applications. It follows a top-down approach, starting from the overall application context (resource level), moving to the specific types of operations (spans) that constitute an agent’s execution, and detailing the attributes associated with each. The schema heavily relies on OpenTelemetry (OTEL) semantic conventions, including the specialized conventions for Generative AI (GenAI).

The goal is to provide a standardized way to capture telemetry data, enabling effective visualization, monitoring, debugging, and performance analysis of agentic AI systems.

2. Resource Level Attributes

These attributes define the service or application performing the operations.

keithchambers

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:

  transform/normalise_keys:
    error_mode: ignore

keithchambers

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AWS Bedrock OpenTelemetry (OTLP/JSON) Schema",
  "description": "Validation schema covering resource and span attributes required for instrumenting Amazon Bedrock calls using OpenTelemetry Gen-AI semantic conventions.",
  "type": "object",
  "properties": {
    "resource": {
      "type": "object",
      "properties": {
        "attributes": { "$ref": "#/$defs/ResourceAttributes" }

keithchambers

// Package genaicleaner provides an OpenTelemetry Collector *processor* that
// sanitises Gen-AI spans in-flight.
//
// The processor performs three operations, all entirely in-memory:
//
//   1. **Validation** – incoming spans are checked against Harrier’s
//      *authoritative* allow-lists (derived from OTEP ≥ 1.43).
//   2. **Cleaning / Forking**
//        • A *clean* copy is forwarded on the same pipeline and tagged
//          `messaging.kafka.destination="input"` so the kafkaexporter can map

keithchambers

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name",         "value": { "stringValue": "autonomous_trading_system" } },
          { "key": "service.namespace",    "value": { "stringValue": "trading" } },
          { "key": "service.version",      "value": { "stringValue": "3.2.0" } },
          { "key": "service.instance.id",  "value": { "stringValue": "instance-001" } },
          { "key": "deployment.environment","value":{ "stringValue": "prod" } }

keithchambers

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name",            "value": { "stringValue": "genai-demo-app" } },
          { "key": "deployment.environment",  "value": { "stringValue": "prod"           } }
        ]
      },
      "schema_url": "https://opentelemetry.io/schemas/1.5.0",

keithchambers

{
  "resourceSpans": [{
    "schemaUrl": "https://opentelemetry.io/schemas/1.25.0",
    "resource": {
      "attributes": [{
        "key": "service.name", "value": { "stringValue": "llm-gateway" }},{
        "key": "deployment.environment", "value": { "stringValue": "prod" }}]},
    "scopeSpans": [{
      "scope": { "name": "ai.request.pipeline", "version": "2.3.0" },
      "spans": [{

keithchambers

#!/bin/bash
set -e # Exit on error. Use `set -eux` for debugging to print commands and expand variables.

REPO_NAME="kafka-batch-upload"
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) # Get dir where setup.sh is
KAFKA_IMAGE="bitnami/kafka:3.7" # Define Kafka image once

echo "Setting up the Kafka Batch Upload project in ./${REPO_NAME}"
echo "This will create all necessary files and directories."
echo "Attempting to automate KRaft Cluster ID generation..."

keithchambers

// Package main implements a load tester for sending OpenTelemetry (OTLP) data
// via HTTP JSON or gRPC Protobuf, with an option to output generated data to a
// file instead of sending it over the network.
package main

import (
	"bytes"
	"context"
	"crypto/tls"
	"encoding/hex"