There are tags that work very well with Lightstep in addition to the OpenTracing semantic conventions. Any tag that you add to your span data will enable more segmentation, making it easier to find, filter, and group your span data in Lightstep. Lightstep doesn’t have cardinality limitations, so the more tags you use, the greater your insights will be.
In particular, tags that allow you to segment user pathways are useful. Adding things like “parameters” (
params.count), that correspond to the operation on the span and tell an operation which path to take depending on user input, are also very helpful for grouping, filtering, and segmenting. Otherwise, you may optimize for one use case without noticing some other outlier use case that only gets triggered 1/4 the time. Correlations will also be able to spot the outliers from these tag values.
Following are recommended tags (other than the OpenTracing tags) that provide greater visibility into your span data.
Best Practice - Use the OpenTracing Tags
Always follow the OpenTracing semantic tag guidelines whenever possible.
params.type, corresponding to the parameters an operation was called with.
response.size_bucket, or other size tags when sending and receiving data.
region, or any sort of regional, zone, or geographical tag.
uuid, or other anonymous identifiers of transactions or of users (or even of user segments or user types).
api.version, or any sort of version tagging on your code in production.
- hardware versions,
platform, or any identifier of the user’s hardware, such as ios 10 or ios 8.
http.status_code_groupsuch as 4xx, 5xx, 2xx.
internal.errorboolean for differentiating when an error is caused by a user, for example a 404, 400 versus 500.
unified_error_code, to quickly figure out the magnitude of exceptions or specific error types that are occurring.
<entity>.idfor the entity that is being fetched from the database or worked with, for example,
project.idif retrieving a project for a user.
grpc.status_code, and codes corresponding to gRPC calls.
max_retry_attemptsin areas of the codebase where there is retry logic.
canary: true/false, or other tags corresponding to when a feature flag or canary/AB test is active or not.
pubsub.message_id, and other tags corresponding to
service.version, and any other tags related to versions of the codebase or library/tool being used. The
service.versiontag is very useful when tracking service deployment performance in Lightstep.
node.id, and any other tags related to Kubernetes (or other container management solutions) to help easily show when a problem is isolated to a particular cluster, pod or node.
stack_trace_hash, the hash of a stack trace when an error has occurred, to easily search for a particular stack trace in Lightstep.
flow, a human-readable name of common flows represented by traces, like
svc.<service_name>.<thing>, service name-spacing for service-specific tags, for example:
- Sanitized payload of a request and a response (clear any personally identifiable information).
- Events that are occurring within the span, for example,
sanitized payload for request, forwarding to <xyz>.
- Stack trace or exception messages and error messages.
- When things are returning, processing, or waiting, for example,
context deadline exceeded. An operation may go for a few seconds and logging can add context on what it’s doing or what it’s waiting for.
- Any additional context. If a user hits a certain flow and it’s non-obvious by the operations, a simple log message can be helpful, for example, “user entered flow x”.