SignalFx Developers Guide

Developer Home

Product Docs

SignalFx
Documentation Powered by ReDoc

µAPM PG Service Map Retrieval API

IMPORTANT: This documentation is for the original SignalFx Microservices APM product released in 2019 that is now known as Microservice APM Previous Generation (µAPM PG). The developer interface for the current µAPM product, released on March 31, 2020, is not available.

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

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

Response Headers
Content-Type
string

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

Response Schema: application/json
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".

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.

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 Previous Generation Inferred Services
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"

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

Response samples

Content type
application/json
{
  • "descriptor":
    {
    },
  • "edges":
    [
    ],
  • "nodes":
    {
    }
}

Retrieve Service Map Using Query

Retrieves service maps based on search criteria

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

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.

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.

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

Response Headers
Content-Type
string

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

Response Schema: application/json
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".

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.

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 Previous Generation Inferred Services
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"

Request samples

Content type
application/json
{
  • "duration":
    {
    },
  • "operations":
    [
    ],
  • "services":
    [
    ],
  • "tags":
    {
    },
  • "time":
    {
    }
}

Response samples

Content type
application/json
{
  • "descriptor":
    {
    },
  • "edges":
    [
    ],
  • "nodes":
    {
    }
}