Naming Spans and Attributes
Span types
Backends may organize spans into categories (or types) depending on the presence of some semantic attributes.
http:service_name
category for spans representing HTTP requests.db:postgresql
for PostgreSQL queries.log:error
for log messages withERROR
severity.exception
for exceptions.
By making sure that spans have correct semantic attributes, you ensure that they are categorized and grouped properly. Which in turn makes filtering and aggregation simpler.
HTTP
To monitor HTTP clients and servers, use HTTP semantic convention.
A minimal HTTP server example:
SpanName = "GET /users/:id"
SpanKind = "server"
http.method = "GET"
http.route = "/users/:id"
A minimal HTTP client example:
SpanName = "GET /users/:id"
SpanKind = "client"
http.method = "GET"
http.route = "/users/:id"
RPC
To monitor remote procedure calls, use RPC semantic convention.
A minimal RPC server example:
SpanName = "AuthService/Auth"
SpanKind = "server"
rpc.system = "grpc"
rpc.service = "AuthService.Auth"
rpc.method = "Auth"
Database
To monitor database queries and Redis/memcached commands, use DB semantic convention.
A minimal DB example:
SpanName = "pg.query"
SpanKind = "client"
db.system = "postgresql"
db.statement = "SELECT * FROM users WHERE id = 123"
A minimal Redis command example:
SpanName = "GET"
SpanKind = "client"
db.system = "redis"
db.statement = "GET foo"
Messages
To monitor producers and consumers (queues), use Messaging semantic convention.
A minimal producer example:
SpanName = "send MyQueue"
SpanKind = "producer"
messaging.system = "rabbitmq"
messaging.destination = "MyQueue"
messaging.destination_kind = "queue"
A minimal consumer example:
SpanName = "process MyQueue"
SpanKind = "consumer"
messaging.system = "rabbitmq"
messaging.operation = "process"
messaging.destination = "MyQueue"
messaging.destination_kind = "queue"
Functions as a Service
To monitor serverless functions, use FaaS semantic convention.
A minimal server example:
SpanName = "my-lambda-function"
SpanKind = "server"
faas.trigger = "http"
faas.name = "my-lambda-function"
A minimal client example:
SpanName = "my-lambda-function"
SpanKind = "client"
faas.trigger = "http"
faas.invoked_name = "my-lambda-function"
Plain functions
To monitor plain functions, use Source code attributes.
A minimal example:
SpanName = "org.FetchUser"
service.name = "myservice"
code.function = "org.FetchUser"
code.filepath = "org/user.go"
code.lineno = "123"
Exceptions
To monitor errors and exceptions, use Exceptions semantic convention and events API.
A minimal example:
EventName = "exception"
exception.type = "*exec.ExitError"
exception.message = "exit status 1"
exception.stack = "<exception stack>"
The same with Go programming language:
span := trace.SpanFromContext(ctx)
span.AddEvent(ctx, "exception",
// Exception type and message.
label.String("exception.type", "*exec.ExitError"),
label.String("exception.message", "exit status 1"),
label.String("exception.stack", string(runtime.Stack())),
)
Logs
A minimal example:
EventName = "log"
log.severity = "info"
log.message = "something failed"
log.params.key1 = "value1"
log.params.key2 = "value2"
Internal pseudo type
internal
is a pseudo type for the spans that can't be categorized using the rules above and that have SpanKind = "internal"
.
If for some reason you want to move a particular group of spans from internal
type, you can either:
- Add proper type-specific semantic attributes.
- Change
SpanKind
to any other valid value (for example,server
orclient
).