SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Service Map Retrieval API

API for retrieving service maps based on trace data, either by searching trace data or by specifying a trace ID.

  • The /servicemap/traces endpoint returns service maps based on traces that match the search criteria you specify in the request body.
  • The /servicemap/trace/{id} endpoint returns the service map of the trace identified in the id path parameter

Retrieve Service Map Trace ID

Retrieves a service map

get /servicemap/trace/{id}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/servicemap/trace/{id}

Retrieves the service map corresponding to the trace that has the ID specified by the id path parameter.

path Parameters
id
required
string

The trace ID of a trace

header Parameters
Content-Type
required
string

Format of the request body. Always application/json.

X-SF-TOKEN
required
string

Authentication token

Responses

200

Successful request

Response Headers
Content-Type
string

Format of the response body. Always "application/json".

Response Schema: application/json
descriptor
object

Object containing a property that describes the type of data used to construct the service map. For a service map based on trace data, the value is always "TRACE".

edges
Array of objects (Single element of the service map edge array)

Array of objects that represent the relationship between two nodes in the service map. Each object contains the source node and destination node of the edge, as well as metadata for the source node.

nodes
object (Dictionary of map nodes in the service map)

Dictionary of service information for each service in the service map, in the form of a JSON object containing a child object for each service. The child object's key is the name of the service. The object contains the following properties:

  • name: The service's name. This value can be from a span, or SignalFx can infer it from a span that calls a remote service.
  • aliases: Aliases for the service name, retrieved from span data
  • data: Metadata for the service
  • inferred:
    If true, SignalFx inferred name and type for this object from span tags in a span that recorded a remote service call.
    If false, the information in this object is for an actual span.
  • type:
    If inferred is true, type is inferred from span tags in a span that recorded a remote service call, and has the value "HTTP", "PUBSUB", "DATABASE", or "CACHE".
    If inferred is false, SignalFx sets the value of type to "UNKNOWN".
    To learn more about inferred services, see the topic Microservices APM Inferred Services
400

Invalid request. The trace ID is unknown.

403

The value of X-SF-TOKEN is invalid.

Response Schema: application/json
code
integer (HTTP response code. Always `403`)

Indicates that the request contains an invalid authentication token

message
string (Error message)

API error response message. Always set to "Problem accessing /v2/servicemap/trace/{id}. Reason: Forbidden"

404

The specified trace ID doesn't exist in the organization.
SignalFx also returns this response code if µAPM tracing isn't implemented in the organization. In this case, the organization doesn't have any trace IDs.

Response Schema: application/json
code
integer (HTTP response code. Always '404')

Indicates that the request contains a trace ID that can't be found

message
string (Error message)

API error response message. Always set to "Trace not found".

500

Internal server error.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "descriptor":
    {
    },
  • "edges":
    [
    ],
  • "nodes":
    {
    }
}

Retrieve Service Map Using Query

Retrieves service maps based on search criteria

post /servicemap/traces

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https:/api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/servicemap/traces

Retrieves the service map corresponding to the traces selected by the search criteria you specify in the request body. To select traces, you can specify the following criteria:

  • Service names: Exact match to one or more service name in the trace data.
  • Operations: Exact match to one or more operations in the trace data.
  • Tags: Exact match to one or more tags
  • Duration range: Range of trace durations to include, in microseconds. You can specify a lower bound, an upper bound, or both. Specifying a duration range is optional.
  • Time range: Range of starting timestamps for spans to include, in microseconds. You can specify a lower bound, an upper bound, or both. Specifying a timestamp range is optional.
header Parameters
Content-Type
required
string

Format of the request body. Always application/json.

X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

Search criteria for the traces that define the service map you want

duration
object

Trace durations to search for. A duration is specified by an upper bound or a lower bound or both. This property is optional; if you omit it, the API ignores trace duration.

operations
Array of strings

List of operation names, in the form of a JSON array. The API searches for traces that have an exact match to all of the operations in the array.

services
Array of strings

List of service names, in the form of a JSON array. The API searches for traces that have an exact match to all of the service names in the array.

tags
object

One or more span tags, in the form of a JSON object containing child properties. Each property represents a span tag name and value. The API searches for traces containing spans that have an exact match to all of the specified tags.

time
object

Span starting timestamps to search for, specified by an upper bound or lower bound or both. This property is optional; if you don't specify it, the API ignores timestamps.
Timestamps are in Unix format in microseconds.

Responses

200

Successful request, or the search failed to find any matching traces. If the search failed to find traces, the response body is empty.

Response Headers
Content-Type
string

Format of the response body. Always "application/json".

Response Schema: application/json
descriptor
object

Object containing a property that describes the type of data used to construct the service map. For a service map based on trace data, the value is always "TRACE".

edges
Array of objects (Single element of the service map edge array)

Array of objects that represent the relationship between two nodes in the service map. Each object contains the source node and destination node of the edge, as well as metadata for the source node.

nodes
object (Dictionary of map nodes in the service map)

Dictionary of service information for each service in the service map, in the form of a JSON object containing a child object for each service. The child object's key is the name of the service. The object contains the following properties:

  • name: The service's name. This value can be from a span, or SignalFx can infer it from a span that calls a remote service.
  • aliases: Aliases for the service name, retrieved from span data
  • data: Metadata for the service
  • inferred:
    If true, SignalFx inferred name and type for this object from span tags in a span that recorded a remote service call.
    If false, the information in this object is for an actual span.
  • type:
    If inferred is true, type is inferred from span tags in a span that recorded a remote service call, and has the value "HTTP", "PUBSUB", "DATABASE", or "CACHE".
    If inferred is false, SignalFx sets the value of type to "UNKNOWN".
    To learn more about inferred services, see the topic Microservices APM Inferred Services
400

Invalid request. One or more of the properties in the request body is not well-formed or has an invalid value.

403

Invalid authentication. The value of X-SF-TOKEN is invalid.

Response Schema: application/json
code
integer (HTTP response code. Always `403`)

Indicates that the request contains an invalid authentication token

message
string (Error message)

API error response message. Always set to "Problem accessing /v2/servicemap/traces. Reason: Forbidden"

500

Internal server error.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "duration":
    {
    },
  • "operations":
    [
    ],
  • "services":
    [
    ],
  • "tags":
    {
    },
  • "time":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "descriptor":
    {
    },
  • "edges":
    [
    ],
  • "nodes":
    {
    }
}

© Copyright 2019 SignalFx.

Third-party license information