Semantic Conventions

OpenTelemetry semantic conventions used by Telegen.

Overview

Telegen follows OpenTelemetry Semantic Conventions for consistent attribute naming across traces, metrics, and logs.

Resource Attributes

Resource attributes describe the entity producing telemetry.

Service

Attribute Type Description Example
service.name string Service name my-api
service.namespace string Service namespace production
service.version string Service version 1.2.3
service.instance.id string Instance ID pod-abc123

Host

Attribute Type Description Example
host.name string Hostname node-1
host.id string Host ID i-1234567890abcdef0
host.type string Host type n1-standard-4
host.arch string Architecture amd64
host.image.name string OS image name ubuntu-22.04
host.image.version string OS image version 22.04.3

Operating System

Attribute Type Description Example
os.type string OS type linux
os.description string OS description Ubuntu 22.04.3 LTS
os.name string OS name Ubuntu
os.version string OS version 22.04.3

Process

Attribute Type Description Example
process.pid int Process ID 12345
process.executable.name string Executable name python
process.executable.path string Executable path /usr/bin/python
process.command string Command python app.py
process.command_line string Full command line python app.py --port=8080
process.owner string Process owner appuser
process.runtime.name string Runtime python
process.runtime.version string Runtime version 3.11.4

Container

Attribute Type Description Example
container.name string Container name my-container
container.id string Container ID abc123...
container.runtime string Container runtime containerd
container.image.name string Image name my-app
container.image.tag string Image tag v1.2.3

Kubernetes

Attribute Type Description Example
k8s.pod.name string Pod name my-pod-abc123
k8s.pod.uid string Pod UID 550a8ab5-...
k8s.namespace.name string Namespace default
k8s.node.name string Node name node-1
k8s.node.uid string Node UID 12345-...
k8s.deployment.name string Deployment my-deployment
k8s.replicaset.name string ReplicaSet my-rs-abc123
k8s.statefulset.name string StatefulSet my-ss
k8s.daemonset.name string DaemonSet my-ds
k8s.job.name string Job my-job
k8s.cronjob.name string CronJob my-cronjob
k8s.container.name string Container name app
k8s.cluster.name string Cluster name prod-cluster

Cloud

Attribute Type Description Example
cloud.provider string Cloud provider aws, gcp, azure
cloud.account.id string Account ID 123456789012
cloud.region string Region us-east-1
cloud.availability_zone string AZ us-east-1a
cloud.platform string Platform aws_eks

HTTP Span Attributes

Client Spans

Attribute Type Description Example
http.request.method string HTTP method GET
url.full string Full URL https://api.example.com/users
url.path string URL path /users
url.query string Query string page=1&limit=10
url.scheme string URL scheme https
server.address string Server hostname api.example.com
server.port int Server port 443
http.response.status_code int Status code 200
network.protocol.version string HTTP version 1.1
user_agent.original string User agent curl/8.0.1

Server Spans

Attribute Type Description Example
http.request.method string HTTP method POST
url.path string URL path /api/users
url.query string Query string id=123
url.scheme string URL scheme https
http.route string Route template /api/users/{id}
http.response.status_code int Status code 201
http.request.body.size int Request body size 1024
http.response.body.size int Response body size 256
client.address string Client IP 10.0.0.1
client.port int Client port 54321

gRPC Span Attributes

Attribute Type Description Example
rpc.system string RPC system grpc
rpc.service string Service name mypackage.MyService
rpc.method string Method name MyMethod
rpc.grpc.status_code int gRPC status 0
rpc.grpc.request.metadata.<key> string Request metadata  
rpc.grpc.response.metadata.<key> string Response metadata  

Database Span Attributes

Attribute Type Description Example
db.system string Database system postgresql
db.connection_string string Connection string (redacted)
db.user string Database user appuser
db.name string Database name mydb
db.statement string SQL statement SELECT * FROM users
db.operation string Operation SELECT
db.sql.table string Table name users
server.address string Server hostname db.example.com
server.port int Server port 5432

Database System Values

Value Database
postgresql PostgreSQL
mysql MySQL
mongodb MongoDB
redis Redis
elasticsearch Elasticsearch
cassandra Cassandra
mssql Microsoft SQL Server
oracle Oracle

Messaging Span Attributes

Attribute Type Description Example
messaging.system string Messaging system kafka
messaging.destination.name string Topic/queue orders
messaging.destination.kind string Destination kind topic
messaging.operation string Operation publish, receive
messaging.message.id string Message ID msg-123
messaging.message.body.size int Body size 512
messaging.kafka.partition int Partition 3
messaging.kafka.offset int Offset 12345
messaging.kafka.consumer_group string Consumer group order-processor

Network Attributes

Attribute Type Description Example
network.transport string Transport tcp, udp
network.type string Network type ipv4, ipv6
network.protocol.name string Protocol http
network.protocol.version string Protocol version 1.1
network.peer.address string Peer address 10.0.0.1
network.peer.port int Peer port 8080
network.local.address string Local address 192.168.1.1
network.local.port int Local port 54321

Exception Attributes

Attribute Type Description Example
exception.type string Exception type java.lang.NullPointerException
exception.message string Exception message Object is null
exception.stacktrace string Stack trace (multiline)
exception.escaped boolean Escaped scope true

Span Status

Status Code Description
Unset 0 Default, not set
Ok 1 Successful
Error 2 Error occurred

Span Kind

Kind Description Example
INTERNAL Internal operation Business logic
SERVER Server-side request HTTP server handler
CLIENT Client-side request HTTP client call
PRODUCER Message producer Kafka producer
CONSUMER Message consumer Kafka consumer

Metric Semantic Conventions

HTTP Metrics

Metric Type Unit Description
http.server.request.duration Histogram s Server request duration
http.server.active_requests UpDownCounter {request} Active requests
http.server.request.body.size Histogram By Request body size
http.server.response.body.size Histogram By Response body size
http.client.request.duration Histogram s Client request duration

RPC Metrics

Metric Type Unit Description
rpc.server.duration Histogram ms Server call duration
rpc.client.duration Histogram ms Client call duration

Database Metrics

Metric Type Unit Description
db.client.connections.usage UpDownCounter {connection} Connections
db.client.connections.max UpDownCounter {connection} Max connections

Log Semantic Conventions

Severity Levels

Level Number Description
TRACE 1 Fine-grained debug
DEBUG 5 Debug information
INFO 9 Informational
WARN 13 Warning
ERROR 17 Error
FATAL 21 Fatal error

Common Log Attributes

Attribute Type Description
log.file.name string Log file name
log.file.path string Log file path
log.iostream string stdout/stderr
log.record.uid string Unique log ID

Telegen-Specific Attributes

In addition to OTel conventions, Telegen adds:

Attribute Type Description
telegen.version string Telegen version
telegen.ebpf.program string eBPF program name
telegen.discovery.source string Discovery source
telegen.profile.type string Profile type

Best Practices

  1. Use standard conventions - Prefer OTel conventions over custom attributes
  2. Add context - Include relevant resource attributes
  3. Low cardinality - Avoid high-cardinality values in metric labels
  4. Sensitive data - Don’t include PII or secrets in attributes
  5. Consistent naming - Follow snake_case for custom attributes

Next Steps

Back to top ↑