Naming Spans and Attributes

Span names

Backends use span names and some attributes to group similar spans together. To group spans properly, give them short and concise names. The total number of unique span names should be less than 1000. Otherwise, you will have too many span groups and your Uptrace experience will suffer.

The following names are good because they are short, distinctive, and help grouping similar spans together:

Span nameComment
GET /projects/:idGood. A route name with placeholders instead of params.
select_projectGood. A function name without arguments.
SELECT * FROM projects WHERE id = ?Good. A database query with placeholders.

The following span names are bad because they contain params and args:

Span nameComment
GET /projects/42Bad. Contains a variable param 42.
select_project(42)Bad. Contains a variable 42.
SELECT * FROM projects WHERE id = 42Bad. Contains a variable arg 42.

For the full list of attributes, see semantic attributes, but here are the most popular attributes to get you started.

AttributeComment
service.nameLogical name of the service. Uptrace provides an overview of all services.
service.versionThe version string of the service API or implementation.
host.nameName of the host. Uptrace provides an overview of all hosts.
deployment.environmentName of the deployment environment (aka deployment tier). Uptrace groups spans from different environments separately.

Span system

Depending on the presence of some semantic attributes, Uptrace assigns each span a system, for example:

  • http:service_name system for HTTP spans.
  • db:postgresql for PostgreSQL queries.
  • log:error for log messages with ERROR severity.
  • exception for exceptions.

Using a system, you can easily filter spans that have the same set of attributes, for example, all database spansopen in new window.

HTTP

To monitor HTTP clients and servers, use HTTP semantic conventionopen in new window.

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 conventionopen in new window.

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 conventionopen in new window.

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 conventionopen in new window.

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 conventionopen in new window.

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 attributesopen in new window.

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 conventionopen in new window 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 system

internal is a special system for 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 or client).
Last Updated: