SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Integrations API

IMPORTANT: The Integrations API supports 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 creating, retrieving, updating, and deleting integrations from external systems to SignalFx.

Integrations store basic information about an external system in SignalFx. They also ensure that the connection is valid before you try to use it.

For example, suppose you want to send detector notifications using Slack. When you integrate Slack with SignalFx as the first step, you get the following:

  • Verification that Slack and SignalFx can communicate
  • A SignalFx-assigned integration ID that links to the integration

To configure alerts that go to Slack from a detector, you specify the Slack integration ID and the Slack channel name.

Each external system has its own integration requirements. Read the documentation for the request body of the POST or UPDATE /integration to learn the requirements for the integration you want.

Authentication

To create, update, delete, or validate integrations, you need to authenticate your request using a session token associated with a SignalFx administrator.

To retrieve integration information, your session token doesn't need to be associated with an administrator. You can also retrieve integrations using an org token.

In the web UI, session tokens are known as user API access tokens, and org tokens are known as access tokens. To learn more about authentication tokens, see the topic Authentication Tokens in the Developers Guide.

Supported service types

SignalFx offers integrations for the following:

  • Monitoring systems such as AWS CloudWatch
  • SSO Authentication systems that use SAML, such as ADFS
  • Notification systems such as PagerDuty

Monitoring integrations

SignalFx integrations APIs support monitoring for the following services:

  • Amazon Web Services (AWS)
  • Google Cloud Platform (GCP)
  • Microsoft Azure
  • NewRelic

SSO Authentication using SAML

SignalFx integration APIs support SAML-based SSO integrations for the following services:

  • Microsoft Active Directory Federation Services (ADFS)
  • Okta
  • OneLogin
  • PingOne

Alert notification systems

SignalFx integration APIs support alert notifications using the following services:

  • Amazon EventBridge
  • BigPanda
  • Jira
  • Microsoft Teams
  • Opsgenie
  • PagerDuty
  • ServiceNow
  • Slack
  • VictorOps
  • Webhook
  • xMatters

NOTE: To ensure backward compatibility, the type property for a Microsoft Teams integration is Office365.

Viewing request body documentation

The request body format for the following operations depends on the type of integration you use:

  • POST /integration
  • PUT /integration/{id}

The response body format for the following operations also depends on the type of integration you use:

  • GET /integration
  • GET /integration/{id}

Retrieve Integrations Using Query

Retrieves integrations based on search criteria

Retrieves one or more integration objects based on a query specified in query parameters encoded on the URL.

NOTE: To ensure security, SignalFx omits some authentication and authorization properties from response objects.

The Retrieve Single Integration section has sample response bodies for each integration type. To see an example for an integration type, choose from the list of types that appear after the Response samples heading.

Jira integration:

The response body for a Jira integration contains a union of the following response properties:

  • Properties common to all integration responses
  • Properties common to all Jira integration responses
  • Authentication credential properties for Jira Cloud integrations
  • Authentication credential properties for Jira Server integrations

Some Jira integration properties are set to null in the response:

  • Optional properties that you didn't specify in your creation request

  • Password or API token, to ensure security

  • Properties not used for a specific type of Jira integration.

    For example, if you integrate with Jira Cloud, the response body contains "username"\: null because username isn't a valid property for a Jira Cloud integration.

query Parameters
name
string

Integration object name to search for. You can use wildcard characters to specify the name:

  • *: Matches a run of any characters in any part of the name
  • ?: Matches any single character in any part of the name
type
string
Enum: "ADFS" "AWSCloudWatch" "AmazonEventBridge" "Azure" "AzureAD" "BigPanda" "GCP" "GoogleSaml" "Jira" "Office365" "Okta" "OneLogin" "Opsgenie" "PagerDuty" "PingOne" "NewRelic" "ServiceNow" "Slack" "VictorOps" "Webhook" "XMatters"

Type of integration to search for. This property is an enumerated string, and only the enumerated values are allowed.

To search for a Microsoft Teams integration, use Office365.

offset
integer <int32> >= 0
Default: 0

0-relative position in the result set where SignalFx should start returning integration objects.

limit
integer <int32> >= 1
Default: 50

Number of integration objects to return from the result set

header Parameters
X-SF-TOKEN
required
string

Authentication token

Responses

Response Schema: application/json
count
integer <int64>

Number of integrations that matched the search criteria. This value is not the number of integrations returned in the response body. To learn more, see the description of results.

Microsoft ADFS Integration (object) or AWS CloudWatch Integration (object) or Amazon EventBridge Integration (object) or Microsoft Azure Active Directory Integration (object) or Microsoft Azure Integration (object) or BigPanda Integration (object) or Google Cloud Platform Integration (object) or Google Cloud Identity Integration (object) or Jira Integration Response (object) or Microsoft Teams Integration (object) or NewRelic Integration (object) or Okta Integration (object) or OneLogin Integration (object) or Opsgenie Integration (object) or PagerDuty Integration (object) or PingOne Integration (object) or ServiceNow Integration (object) or Slack Integration (object) or VictorOps Integration (object) or Webhook Integration (object) or xMatters Integration (object)

List of integrations, in the form of a JSON array of JSON objects. Each object contains properties that are common to all integrations as well as properties that are specific to the integration type (type property) for the object.

The size of results and the value of count are not necessarily equal:

  • If you don't specify limit or offset: If count > 50, then sizeOf(results) = 50; otherwise sizeOf(results) = count.
  • If you only specify limit: If count > limit then sizeOf(results) = limit; otherwise sizeOf(results) = count.
  • If you specify limit and offset: If count > (offset + limit) then sizeOf(results) = limit; otherwise, sizeOf(results) = limit.

Response samples

Content type
application/json
{
  • "count": 0,
  • "results":
    {
    }
}

Create Integration

Creates an integration

Creates an integration object that SignalFx uses to connect with a monitoring, SSO, or alerting service. The steps for establishing a connection to a service differ for each type of service and may differ for individual services.

Each service has specific information requirements for integrating with SignalFx.

NOTES:

  • To ensure security, SignalFx omits authentication and authorization properties from response objects.
  • In the response object, the "enabled" property is always set to true.

Jira integration: For a Jira integration request, the response body contains a union of the following response properties:

  • Properties common to all integration responses
  • Properties common to all Jira integration responses
  • Authentication credential properties for Jira Cloud integrations
  • Authentication credential properties for Jira Server integrations

Some Jira integration properties are set to null in the response:

  • Optional properties that you didn't specify in your creation request

  • Password or API token, to ensure security

  • Properties not used for a specific type of Jira integration.

    For example, if you integrate with Jira Cloud, the response body contains "username": null because username isn't a valid property for a Jira Cloud integration.

query Parameters
skipValidation
boolean

Flag that controls how SignalFx validates an alert integration object. If true, SignalFx doesn't send a test notification.

header Parameters
Content-Type
required
string

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

X-SF-TOKEN
required
string

Authentication token. Must be a session token (User API access token) associated with a SignalFx user who has administrative privileges.

Request Body schema: application/json

Properties of the integration.

NOTE: Because this is a request to create a new integration, you must specify the "type" and "name" properties:

  • "type" determines the type of integration that SignalFx creates.
  • "name" provides a unique name for the integration.
One of
enabled
boolean (Integration Enabled Flag)

Indicates the state of the integration. If true, the integration is enabled. If false, the integration is disabled, and you must enable it by setting "enabled" to true in a PUT request that updates the object.

When you create an integration, set this property according to the instructions in the product documentation. Some integrations, such as AWS, expect the initial value to be false, which lets you create the integration and use its properties to set values in AWS.

id
string (SignalFx Integration ID)

SignalFx-assigned ID of the integration. Use this property to refer to an integration using the GET, PUT, or DELETE /integration/{id} endpoints or the GET /integration/validate{id}/ endpoint.

name
string (Integration Label)

Human-readable label for the integration. Use this property to identify a specific integration when you're using multiple integrations for the same service.

issuerUrl
string <uri> (SAML Integration Entity URL)

URL of the entity that issued the certificate for a SAML integration

metadata
string (SAML Integration Metadata Filename)

File name of the SAML metadata XML file for the integration: FederationMetadata.xml

publicKey
string <publickey> (SAML Integration PEM File)

Contents of the certificate.pem file for the public key associated with the SAML integration

type
required
string
Value: "ADFS"

Type of service that this integration represents, in the form of an enumerated string, always "ADFS".

Responses

Response Schema: application/json
One of
created
integer <int64> (Integration Creation Time)

Date and time the integration was created, in the form of a Unix timestamp.

Set by SignalFx; read-only

creator
string (Integration Creator ID)

SignalFx-assigned user ID of the user that created the integration. If SignalFx created the object, the value is "AAAAAAAAAA". Set by SignalFx; read-only

enabled
boolean (Integration Enabled Flag)

Indicates the state of the integration. If true, the integration is enabled. If false, the integration is disabled, and you must enable it by setting "enabled" to true in a PUT request that updates the object.

When you create an integration, set this property according to the instructions in the product documentation. Some integrations, such as AWS, expect the initial value to be false, which lets you create the integration and use its properties to set values in AWS.

id
string (SignalFx Integration ID)

SignalFx-assigned ID of the integration. Use this property to refer to an integration using the GET, PUT, or DELETE /integration/{id} endpoints or the GET /integration/validate{id}/ endpoint.

lastUpdated
integer <int64> (Integration Last Updated Timestamp)

The date and time the integration was last updated, in the form of a Unix timestamp.

Set by SignalFx; read-only

lastUpdatedBy
string (Integration Last Updater ID)

SignalFx-assigned ID of the user who last updated the integration. If SignalFx last updated the integration, the value is "AAAAAAAAAA". Set by SignalFx; read-only

name
string (Integration Label)

Human-readable label for the integration. Use this property to identify a specific integration when you're using multiple integrations for the same service.

issuerUrl
string <uri> (SAML Integration Entity URL)

URL of the entity that issued the certificate for a SAML integration

metadata
string (SAML Integration Metadata Filename)

File name of the SAML metadata XML file for the integration: FederationMetadata.xml

publicKey
string <publickey> (SAML Integration PEM File)

Contents of the certificate.pem file for the public key associated with the SAML integration

type
required
string
Value: "ADFS"

Type of service that this integration represents, in the form of an enumerated string, always "ADFS".

Response Schema: application/json
One of
One of
code
integer

HTTP response code. Always 401 (Unauthorized)

message
string

Human-readable text message for the error. Always "Problem accessing /v2/integration. Reason: Unauthorized"

Response Schema: application/json
One of
code
integer

HTTP response code. Always 500 (Internal Server Error)

message
string

Human-readable error text. Has the form "Integration type 'x' not found" where x is the integration type specified in the request

Request samples

Content type
application/json
Example