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 a 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 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 payload. Must be application/json.

X-SF-Token
required
string

A valid session token (referred to as a user API access token in the web UI). The user associated with this token must have permission to access trace data.

Request Body schema: application/json
services
Array of string

Array of service names. The API searches for traces that have an exact match to all of the service names in the array.

operations
Array of string

Array of operation names. The API searches for traces that have an exact match to all of the operations in the array.

tags
object

Object containing one or more properties representing span tags. The API searches for traces containing spans that have an exact match to all of the specified tags.

duration
object

Object that specifies trace durations to search for, in terms of an lower bound or upper bound or both. This property is optional; if you don't specify it, the API ignores trace duration.

time
object

Object that specifies span starting timestamps to search for, in terms of an lower bound or upper bound or both. This property is optional; if you don't specify it, the API ignores timestamps as a criteria.

Responses

200

Successful request. The API returns a service map that includes the selected traces.

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
required
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string

Specifies the format of the response payload. Always set to "application/json".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

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

nodes
object

Contains one property for each service in the service map. The property's key is the name of the service. The property's value is an object containing three properties:

  • name: The service name
  • aliases: Service name aliases specified in span data
  • data: Metadata for the node
edges
Array of object (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.

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 or the user that it represents does not have permission to view the requested data.

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
{
  • "services":
    [
    ],
  • "operations":
    [
    ],
  • "tags":
    {
    },
  • "duration":
    {
    },
  • "time":
    {
    }
}

Response samples

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

Retrieve Servicemap using trace ID

Retrieves a service map specified in the {id} path parameter

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 a trace specified by the id path parameter.

path Parameters
id
required
string

The trace ID of a trace in the SignalFx organization associated with the access token

header Parameters
Content-Type
required
string

Format of the request payload. Must be application/json.

X-SF-Token
required
string

A valid session token (referred to as a user API access token in the web UI). The user associated with this token must have permission to access trace data.

Responses

200

Successful request. The response body contains the service map for the specified trace ID.

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
required
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string

Specifies the format of the response payload. Always set to "application/json".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

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

nodes
object

Contains one property for each service in the service map. The property's key is the name of the service. The property's value is an object containing three properties:

  • name: The service name
  • aliases: Service name aliases specified in span data
  • data: Metadata for the node
edges
Array of object (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.

400

Invalid request. The trace ID is unknown.

403

Invalid authentication. The value of X-SF-Token is invalid or the user that it represents does not have permission to view the requested data.

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"

500

Internal server error.

Response samples

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

© Copyright 2019 SignalFx.

Third-party license information