Tracer and span mappings
StackState Self-hosted v5.1.x
Last updated
StackState Self-hosted v5.1.x
Last updated
Before we jump into the nitty-gritty of the actual code we can write for a OpenTelemetry instrumentation, let's first look at the key-value pairs that are in spans and where this can be found in the StackState UI.
The span key values should be included when you create spans inside the manual OpenTelemetry instrumentation.
We will get to a few code examples later on in the documentation.
For StackState to understand your data, a tracer name and version needs to be passed with your instrumentation.
StackState requires the following name and version to be set:
Tracer name: @opentelemetry/instrumentation-stackstate
Version: 1.0.0
➡️
When the is to DEBUG
, a message will be returned if a wrong tracer name has been used. The message will warn about an unknown instrumentation and state the tracer name that was passed to it.
The table below provides a summary of all the span keys that can be provided and are required. Further details of each key can be found in the sections below.
Key
Type
Required
Allowed Value
Example
string
yes
Any string
RDS Database: Perspective Name
string
yes
Any string
RDS Database: Service Name
string
yes
Any string
AWS RDS
string
yes
Any string
aws:rds:database:hello-world
string
yes
Any string
Database
number
no
HTTP status
200
Key
trace.perspective.name
Type
string
Example
RDS Database: Perspective Name
Example of where the trace.perspective.name is displayed within the Traces Perspective
In the navigation bar, click Traces Perspective
Find the trace in the list of traces and click on it to expand the trace (There might be multiple traces, make sure you select one that contains your span).
You will notice that a horizontal graph line will contain the name of your component as seen below.
The value from service.name
is used as a primary means to identify a component in the StackState Topology Perspective. A spans.serviceName
key is also created in the Traces Perspective to identify if the trace in the Traces Perspective matches the component in the Topology Perspective.
Key
service.name
Type
string
Example
RDS Database: Service Name
Example of how you can search for your service.name
within the Advanced Filter
section in the Topology view
When on the Topology Perspective page click on the second icon on your left navigation bar called View Filters
This will bring up the Filter Topology
view, Click on the second button called Advanced
In the top input field you can fill in the following
name = "<YOUR service.name VALUE>"
For example name = "RDS Database: Service Name"
.
You will then see the component that was created with the trace.
Key
service.type
Type
string
Example
AWS RDS
Example of where the service.type
is displayed within the Traces Perspective Span properties view
In the navigation bar, click Traces Perspective
Find the trace in the list of traces and click on it to expand the trace (There might be multiple traces, make sure you select one that contains your trace).
Click on the SHOW ALL PROPERTIES
button on the right side, a popup will appear.
A row with the key service
will contain the value you defined, as seen below in the image.
The service identifier is used for merging components. The provided value will be added to the identifier list on the component in StackState.
Components with the same service identifiers will merge into one component. This allows multiple components to merge and create relations. Components can also bo merged with existing StackState components.
Key
service.identifier
Type
string
Example
aws:rds:database:hello-world
Example of where the service.identifier
is displayed within the Topology Perspective Component properties view
Click on your component in the StackState Topology Perspective
Click on the SHOW ALL PROPERTIES
button on the right side, a popup will appear.
The row with the key identifiers
will contain the value you defined, as seen below in the image.
The resource name is displayed in the Traces Perspective for a specific trace, allowing you to quickly identify what resource each trace is a part of. Best practise would be to use this value to group similar resources, thus allowing you to easily identify a span.
Key
resource.name
Type
string
Example
Database
Example of where the resource.name is displayed within the Traces Perspective
In your top navigation bar click on the trace perspective
menu item.
Find the trace in the list of traces and click on it to expand the trace (There might be multiple traces, make sure you select one that contains your trace).
The section on your right side will contain a row with the key Resource
, the value displayed next to the key will be the one you defined.
The HTTP status code controls the health state for the component in StackState. A 400
or higher will put the component into a CRITICAL state, while a 200
will result in a healthy component. This allows you to control the health state of the component in StackState.
Key
http.status_code
Type
number
Example
200
You will see the following color on your component if you post a http.status_code
of 200
This means that your component is in a CLEAR (healthy) state.
The trace.perspective.name
is used to find your span within a trace in the StackState UI . The horizontal bar within a Trace will have a floating text value containing the specified trace.perspective.name
key.
The service.type
is used to identify the type of service in the span in the StackState UI .
➡️
NB. It's recommended to go and read the page to know how this value can be leverage to create relations
➡️