SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

µAPM PG Trace 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 Microservice APM Previous Generation (µAPM PG) trace data from SignalFx

If you're an Enterprise customer, you can use POST /trace/outliers to find the traces that are the biggest contributors to latency.

Retrieve Trace Data

Retrieves traces specified by search criteria

Retrieves traces based on search criteria specified in the request body

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

object

Filter criteria for the duration of an operation, specified as elapsed times in microseconds

Both the gte and lte properties are optional:

  • If you don't specify them ("duration": {}), the API returns tags regardless of their duration.
  • If you specify gte but not lte, the API returns tags with no upper bound for duration and an lower bound of gte.
  • If you specify lte but not gte, the API returns tags with no lower bound for duration and an upper bound of lte.
object (Span End Time Filter)

Filter criteria for a span's end time. This property is optional, and you can specify it as "endTime": {}".

Considerations:

  • If you omit the property or specify a null value, the API doesn't filter the results for span end times.

  • If you specify the gte property but not the lte property, the API filters for spans where
    "gte value <= span end time <= latest span end time" is true.

  • If you specify the lte property but not the gte property, the API filters for spans where
    "earliest span end time <= span end time <= lte value" is true.

  • If you specify both gte and lte, the API filters for spans where
    "gte value <= span end time <= lte value" is true.

object

Additional filters for the services and operations you want. Each filter is an array of tags that the API compares to the services and operations you specify in the search criteria.

The value of filters is an object containing one or more properties. Each property has this format:

  • key: A name for an array of tags
  • value: An array of tags
operations
Array of strings

List of operations for which you want traces, in the form of a JSON array. Each element contains the name of a single operation.

services
Array of strings

Names of one or more services for which you want traces, in the form of a JSON array. Each element specifies a single service name.

object

Container for sets of compound, span-level search criteria, in the form of a JSON object.

object (Span Start Time Filter)

Filter criteria for a span's start time. This property is optional, and you can specify it as "startTime": {}".

Considerations:

  • If you omit the property or specify a null value, the API doesn't filter the results for span start times.
  • If you specify the gte property but not the lte property, the API filters for spans where
    "gte value <= span start time <= latest span start time" is true.
  • If you specify the lte property but not the gte property, the API filters for spans where
    "earliest span start time <= span start time <= lte value" is true.
  • If you specify both gte and lte, the API filters for spans where
    "gte value <= span start time <= lte value" is true.
status
string
Enum: "ALL_ERRORS" "ANY" "ENDPOINT_ERRORS" "TRACE_ERRORS"

String specifying the type of error tracing data to show. The valid values are:

  • ALL_ERRORS: Select traces that have errors anywhere in the trace
  • ENDPOINT_ERRORS: Select traces only if they have have
    errors in an endpoint operation between services
  • TRACE_ERRORS: Select traces only if they have errors in the initiating operation
  • ANY: Select traces with any status
object

Filter criteria for the duration of an operation, specified as starting and ending timestamps in microseconds

Both the gte and lte properties are optional:

  • If you don't specify either property ("time": {}), the API returns tags regardless of their start and end times.
  • If you specify gte but not lte, the API returns tags with no maximum start time and a minimum start time of gte
  • If you specify lte but not gte, the API returns tags with no minimum end time and a maximum end time of lte.

Responses

Response Headers
Content-Type
string

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

Response Schema: application/json
object

Bar chart buckets for the time distribution of errors in the retrieved traces

Array of objects (A single trace group)

List of trace groups for the retrieved data, in the form of a JSON array.

A trace group is a set of traces that all have the same trace identity. If relevant, this includes the initiating service and HTTP method.

object
  • Histogram buckets for the overall distribution of latency values for the retrieved traces
  • Confidence values for the histogram
object

Descriptor, data type, edges, and nodes for the service map that represents the retrieved traces

object

Lower and upper timestamp boundaries for the retrieved traces, in the form of a JSON object

sampled
boolean

Indicates that the API sampled the result set from the database. A true value means that the API reached its search limit before it found all the available results. You should set more restrictive search criteria and resubmit the request.

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

Indicates that the request contains an invalid authentication token

message
string (Error message)

API error response message

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

Indicates that the µAPM PG API is not implemented in your organization.

message
string (Error message)

API error response message. Always set to "HTTP 403 Forbidden"

Request samples

Content type
application/json
{
  • "duration":
    {
    },
  • "endTime":
    {
    },
  • "filters":
    {
    },
  • "operations":
    [
    ],
  • "services":
    [
    ],
  • "spans":
    {
    },
  • "startTime":
    {
    },
  • "status": "ALL_ERRORS",
  • "time":
    {
    }
}

Response samples

Content type
application/json
{
  • "barChart":
    {
    },
  • "groups":
    [
    ],
  • "histogram":
    {
    },
  • "map":
    {
    },
  • "range":
    {
    },
  • "sampled": true
}

Retrieve Trace Data Operation Name

Retrieves operation names and endpoints

Retrieves endpoints and operations for traces.

If you specify the cluster query parameter, the API only returns endpoints and operations for data transmitted through one of the Smart Gateways associated with the cluster.

If you specify the services query parameter, the API only returns endpoints and operations for spans that contain that service.

The API lets you specify multiple instances of the services parameter. Using this feature, you can use a set of services. The resulting filter is a logical OR of the individual values.

query Parameters
cluster
string

Smart Gateway cluster name.

Clusters are load-balanced sets of Smart Gateway instances that work together to handle large volumes of data.

If you don't specify a value, SignalFx returns data for all of the Smart Gateway clusters for your organization.

services
string

Service name or names to use as filter criteria for the returned data.

If this parameter is present, the API only returns operations associated with the specified services.

To specify more than one name, use multiple instances of services= separated by &. For example, to search for data that includes the db1 or db2 service na