Naming Spans and Attributes

• Span names
• Resource attributes
• Span system
  • HTTP
  • RPC
  • Database
  • Messages
  • Functions as a Service
  • Plain functions
  • Exceptions
  • Logs
  • Internal system

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 experience may suffer.

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

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

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

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

Resource attributes

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

Attribute	Comment
service.name	Logical name of the service. Uptrace provides an overview of all services.
service.version	The version string of the service API or implementation.
deployment.environment	Name of the deployment environment (aka deployment tier). Uptrace groups spans from different environments separately.
host.name	Name of the host. Usually, resource detectors discover and set this attribute automatically.

You can set those attributes by providing the OTEL_RESOURCE_ATTRIBUTES environment variable:

export OTEL_RESOURCE_ATTRIBUTES=service.name=myservice,service.version=1.0.0,deployment.environment=production

Or you can configure them during OpenTelemetry initialization:

// https://uptrace.dev/get/uptrace-go.html

import "github.com/uptrace/uptrace-go/uptrace"

uptrace.ConfigureOpentelemetry(
    // copy your project DSN here or use UPTRACE_DSN env var
    //uptrace.WithDSN("https://<token>@uptrace.dev/<project_id>"),

	uptrace.WithServiceName("myservice"),
	uptrace.WithServiceVersion("v1.0.0"),
	uptrace.WithDeploymentEnvironment("production"),
)

# https://uptrace.dev/get/uptrace-python.html

import uptrace

# copy your project DSN here or use UPTRACE_DSN env var
uptrace.configure_opentelemetry(
  dsn="https://<token>@uptrace.dev/<project_id>",
  service_name="myservice",
  service_version="1.0.0",
  deployment_environment="production",
)

# https://uptrace.dev/get/uptrace-ruby.html

require 'uptrace'

# copy your project DSN here or use UPTRACE_DSN env var
Uptrace.configure_opentelemetry(dsn: 'https://<token>@uptrace.dev/<project_id>') do |c|
  # c is OpenTelemetry::SDK::Configurator
  c.service_name = 'myservice'
  c.service_version = '1.0.0'

  c.resource = OpenTelemetry::SDK::Resources::Resource.create(
    'deployment.environment' => 'production'
  )
end

// https://uptrace.dev/get/uptrace-js-node.html

const uptrace = require('@uptrace/node')

uptrace
  .configureOpentelemetry({
    // copy your project DSN here or use UPTRACE_DSN env var
    //dsn: 'https://<token>@uptrace.dev/<project_id>',
    serviceName: 'myservice',
    serviceVersion: '1.0.0',
    deploymentEnvironment: 'production',
  })
  // Start OpenTelemetry SDK.
  .start()
  // Then execute the main function when SDK is ready.
  .then(main)

// https://uptrace.dev/get/uptrace-php.html

$conf = new Uptrace\Config();
// copy your project DSN here or use UPTRACE_DSN env var
//$conf->setDsn('https://<token>@uptrace.dev/<project_id>');
$conf->setServiceName('myservice');
$conf->setServiceVersion('1.0.0');
$conf->setDeploymentEnvironment('production');

$uptrace = new Uptrace\Distro($conf);
$tracerProvider = $uptrace->createTracerProvider();

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 spans.

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 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).