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

• Metrics Reference - Available metrics

• Distributed Tracing - Tracing details

• OTel Semantic Conventions