Skip to main content

ServiceNow Cloud Observability (formerly Lightstep)

Reading time: 0 minute(s) (0 words)

ServiceNow Cloud Observability (formerly Lightstep) features distributed tracing that can be used to rapidly pinpoint the causes of failures and poor performance across the deeply complex dependencies among services, teams, and workloads in modern production systems. Nobl9 integration with ServiceNow Cloud Observability facilitates organizations to establish service level objectives from performance data captured through distributed traces in the ServiceNow Cloud Observability platform.

Scope of support​

ServiceNow Cloud Observability parameters and supported features in Nobl9
General support:
Release channel: Stable, Beta
Connection method: Agent, Direct
Replay and SLI Analyzer: Historical data limit 30 days
Event logs: Supported
Query checker: Not supported
Query parameters retrieval: Supported
Timestamp cache persistence: Supported
Query parameters:
Query interval: 1 min
Query delay: 2 min
Jitter: 15 sec
Timeout: 30 sec
Agent details and minimum required versions for supported features:
Plugin name: n9lightstep
Query delay environment variable: LS_QUERY_DELAY
Replay and SLI Analyzer: 0.65.0
Query parameters retrieval: 0.73.2
Timestamp cache persistence: 0.65.0

You can configure Nobl9 SLOs with ServiceNow Cloud Observability by using one of the following metric types:

  • ServiceNow Cloud Observability Unified Query Language (UQL)

    • Nobl9 supports constant, metrics, and spans query types in the UQL for both, Threshold and Ratio metric types

      caution

      Nobl9 does not support creating SLOs with the following ServiceNow Cloud Observability UQL queries: spans_sample and assemble.

  • Latency Threshold for Threshold metric type

  • Error Threshold for Threshold metric type

  • Error Ratio for Ratio metric type

Learn more about available metric types.

Authentication​

Before making an API call to ServiceNow Cloud Observability, Nobl9 needs to pass the following credentials:

  • Lightstep Organization ID: you can retrieve the organization ID from the Settings tab in ServiceNow Cloud Observability UI.

  • Lightstep Project Name. For details on how to create your ServiceNow Cloud Observability projects, go here.

  • Lightstep Stream ID. It is an ID of a metric stream created in ServiceNow Cloud Observability. There are several ways to obtain the Stream ID (refer to How to Obtain Stream ID? for more details):

    • The Stream ID is described in the ServiceNow Cloud Observability documentation: How to Create Stream in Lightstep? | Lightstep documentation

    • In the Lightstream UI:

      1. Select a service.

      2. Go to the Streams tab.

      3. Open the selected stream.

      Your stream ID can be obtained from a URL of the stream details page:

      Image 1: Lightstream UI - stream ID example

ServiceNow Cloud Observability (Lightstep) API token​

When deploying the Nobl9 agent, provide the LS_APP_TOKEN environment variable for authentication with the ServiceNow Cloud Observability Streams Timeseries API. To obtain it, create a ServiceNow Cloud Observability API key.

When setting up the direct connection to ServiceNow Cloud Observability, provide your created API key in the Lightstep App Token field.

Adding ServiceNow Cloud Observability as a data source​

To ensure data transmission between Nobl9 and ServiceNow Cloud Observability, it may be necessary to list Nobl9 IP addresses as trusted.

💻ip allowlist
IP addresses to include in your allowlist for secure access:

If you're using app.nobl9.com instance:
  • 18.159.114.21
  • 18.158.132.186
  • 3.64.154.26
If you're using us1.nobl9.com instance:
  • 34.121.54.120
  • 34.123.193.191
  • 34.134.71.10
  • 35.192.105.150
  • 35.225.248.37
  • 35.226.78.175
  • 104.198.44.161

You can add the ServiceNow Cloud Observability data source using the direct or agent connection methods.

Direct connection method​

Direct connection to ServiceNow Cloud Observability requires users to enter their credentials which Nobl9 stores safely.

Nobl9 Web​

To set up this type of connection:

  1. Navigate to Integrations > Sources.
  2. Click .
  3. Click the required Source button.
  4. Choose Direct.
  1. Select one of the following Release Channels:
    • The stable channel is fully tested by the Nobl9 team. It represents the final product; however, this channel does not contain all the new features of a beta release. Use it to avoid crashes and other limitations.
    • The beta channel is under active development. Here, you can check out new features and improvements without the risk of affecting any viable SLOs. Remember that features in this channel can change.

  2. Enter the name of the Lightstep Organization to connect to your data source (mandatory).
    More about the Lightstep organization.

  3. Enter a name in the Lightstep Project field (mandatory).
    More about the Lightstep project.

  4. Enter the Lightstep App Token (mandatory).
    More about ServiceNow Cloud Observability API token.

  1. Select a Project.
    Specifying a project is helpful when multiple users are spread across multiple teams or projects. When the Project field is left blank, Nobl9 uses the default project.
  2. Enter a Display Name.
    You can enter a user-friendly name with spaces in this field.
  3. Enter a Name.
    The name is mandatory and can only contain lowercase, alphanumeric characters, and dashes (for example, my-project-1). Nobl9 duplicates the display name here, transforming it into the supported format, but you can edit the result.
  4. Enter a Description.
    Here you can add details such as who is responsible for the integration (team/owner) and the purpose of creating it.
  5. Specify the Query delay to set a customized delay for queries when pulling the data from the data source.
    • The default value in ServiceNow Cloud Observability integration for Query delay is 1 minute.
    info
    Changing the Query delay may affect your SLI data. For more details, check the Query delay documentation.
  6. Enter a Maximum Period for Historical Data Retrieval.
    • This value defines how far back in the past your data will be retrieved when replaying your SLO based on this data source.
    • The maximum period value depends on the data source.
      Find the maximum value for your data source.
    • A greater period can extend the loading time when creating an SLO.
      • The value must be a positive integer.
  7. Enter a Default Period for Historical Data Retrieval.
    • It is used by SLOs connected to this data source.
    • The value must be a positive integer or 0.
    • By default, this value is set to 0. When you set it to >0, you will create SLOs with Replay.
  8. Click Add Data Source.
caution

ServiceNow Cloud Observability does not recognize the distinction between missing data and valid data with a 0 value in the stream. In such cases, ServiceNow Cloud Observability considers these values to be equal and returns the 0 value.

sloctl​

  1. Create a YAML definition to set up a direct connection with ServiceNow Cloud Observability. For this, refer to the following example:
YAML definition for the direct connection method
apiVersion: n9/v1alpha
kind: Direct
metadata:
  name: lightstep
  displayName: Lightstep Direct
  project: default
spec:
  description: Example Lightstep Direct
  releaseChannel: stable
  lightstep:
    organization: MyOrg
    project: prod-app
    appToken: "[secret]"
    url: https://api.lightstep.com
  historicalDataRetrieval:
    maxDuration:
      value: 30
      unit: Day
    defaultDuration:
      value: 15
      unit: Day
    triggeredBySloCreation:
      value: 15
      unit: Day
    triggeredBySloEdit:
      value: 15
      unit: Day
  queryDelay:
    value: 3
    unit: Minute
FieldTypeDescription
queryDelay.unit
mandatory
enumSpecifies the unit for the query delay. Possible values: Second | Minute.
• Check query delay documentation for default unit of query delay for each source.
queryDelay.value
mandatory
numericSpecifies the value for the query delay.
• Must be a number less than 1440 minutes (24 hours).
• Check query delay documentation for default unit of query delay for each source.
logCollectionEnabled
optional
booleanOptional. Defaults to false. Set to true if you'd like your direct to collect event logs. Contact us to activate it.
releaseChannel
mandatory
enumSpecifies the release channel. Accepted values: beta | stable.
Source-specific fields
lightstep.organization
mandatory
stringServiceNow Cloud Observability requires the name of organization registered in ServiceNow Cloud Observability, the name of the project, and the appToken. See authentication for more details.
lightstep.project
mandatory
string, secretSee authentication section above for more details.
lightstep.appToken
mandatory
string, secretSee authentication section above for more details.
lightstep.url
optional
stringA URL of the ServiceNow Cloud Observability instance. When no value provided, the default https://api.lightstep.com is used.
Replay-related fields
historicalDataRetrieval
optional
n/aOptional structure related to configuration related to Replay.
❗ Use only with supported sources.
• If omitted, Nobl9 uses the default values of value: 0 and unit: Day for maxDuration and defaultDuration.
maxDuration.value
optional
numericSpecifies the maximum duration for historical data retrieval. Must be integer ≥ 0. See Replay documentation for values of max duration per data source.
maxDuration.unit
optional
enumSpecifies the unit for the maximum duration of historical data retrieval. Accepted values: Minute | Hour | Day.
defaultDuration.value
optional
numericSpecifies the default duration for historical data retrieval. Must be integer ≥ 0 and ≤ maxDuration.
defaultDuration.unit
optional
enumSpecifies the unit for the default duration of historical data retrieval. Accepted values: Minute | Hour | Day.
  1. Apply your YAML definition using the sloctl apply command.

Important notes:

  • ServiceNow Cloud Observability requires the name of organization registered in ServiceNow Cloud Observability, the name of the project, and the appToken. Refer to the Authentication section for more details.

  • spec.historicalDataRetrieval - refer to Replay documentation for more details.

  • You can update the lightstep.url with sloctl or Nobl9 Terraform provider.

Agent connection method​

Nobl9 Web​

Follow the instructions below to set up an agent connection.

  1. Navigate to Integrations > Sources.
  2. Click .
  3. Click the required Source button.
  4. Choose Agent.
  1. Select one of the following Release Channels:
    • The stable channel is fully tested by the Nobl9 team. It represents the final product; however, this channel does not contain all the new features of a beta release. Use it to avoid crashes and other limitations.
    • The beta channel is under active development. Here, you can check out new features and improvements without the risk of affecting any viable SLOs. Remember that features in this channel can change.

  2. Enter the name of the Lightstep Organization to connect to your data source (mandatory).

  3. Enter a name in the Lightstep Project field (mandatory).

  1. Select a Project.
    Specifying a project is helpful when multiple users are spread across multiple teams or projects. When the Project field is left blank, Nobl9 uses the default project.
  2. Enter a Display Name.
    You can enter a user-friendly name with spaces in this field.
  3. Enter a Name.
    The name is mandatory and can only contain lowercase, alphanumeric characters, and dashes (for example, my-project-1). Nobl9 duplicates the display name here, transforming it into the supported format, but you can edit the result.
  4. Enter a Description.
    Here you can add details such as who is responsible for the integration (team/owner) and the purpose of creating it.
  5. Specify the Query delay to set a customized delay for queries when pulling the data from the data source.
    • The default value in ServiceNow Cloud Observability integration for Query delay is 1 minute.
    info
    Changing the Query delay may affect your SLI data. For more details, check the Query delay documentation.
  6. Enter a Maximum Period for Historical Data Retrieval.
    • This value defines how far back in the past your data will be retrieved when replaying your SLO based on this data source.
    • The maximum period value depends on the data source.
      Find the maximum value for your data source.
    • A greater period can extend the loading time when creating an SLO.
      • The value must be a positive integer.
  7. Enter a Default Period for Historical Data Retrieval.
    • It is used by SLOs connected to this data source.
    • The value must be a positive integer or 0.
    • By default, this value is set to 0. When you set it to >0, you will create SLOs with Replay.
  8. Click Add Data Source.
  9. Deploy your agent in a Kubernetes cluster or Docker container.

sloctl​

  1. Create a YAML definition to set up an agent connection with ServiceNow Cloud Observability. For this, refer to the following example:
YAML definition for the agent connection method
apiVersion: n9/v1alpha
kind: Agent
metadata:
  name: lightstep
  displayName: Lightstep Agent
  project: default
spec:
  description: Example Lightstep Agent
  releaseChannel: stable
  lightstep:
    organization: MyOrg
    project: prod-app
    url: https://api.lightstep.com
  historicalDataRetrieval:
    maxDuration:
      value: 30
      unit: Day
    defaultDuration:
      value: 15
      unit: Day
  queryDelay:
    value: 3
    unit: Minute
FieldTypeDescription
queryDelay.unit
mandatory
enumSpecifies the unit for the query delay. Possible values: Second | Minute.
• Check query delay documentation for default unit of query delay for each source.
queryDelay.value
mandatory
numericSpecifies the value for the query delay.
• Must be a number less than 1440 minutes (24 hours).
• Check query delay documentation for default unit of query delay for each source.
releaseChannel
mandatory
enumSpecifies the release channel. Accepted values: beta | stable.
Source-specific fields
lightstep.organization
mandatory
stringServiceNow Cloud Observability requires the name of organization registered in ServiceNow Cloud Observability, the name of the project, and the appToken. See authentication for more details.
lightstep.project
mandatory
string, secretSee authentication section above for more details.
lightstep.url
optional
stringA URL of the ServiceNow Cloud Observability instance. When no value provided, the default https://api.lightstep.com is used.
Replay-related fields
historicalDataRetrieval
optional
n/aOptional structure related to configuration related to Replay.
❗ Use only with supported sources.
• If omitted, Nobl9 uses the default values of value: 0 and unit: Day for maxDuration and defaultDuration.
maxDuration.value
optional
numericSpecifies the maximum duration for historical data retrieval. Must be integer ≥ 0. See Replay documentation for values of max duration per data source.
maxDuration.unit
optional
enumSpecifies the unit for the maximum duration of historical data retrieval. Accepted values: Minute | Hour | Day.
defaultDuration.value
optional
numericSpecifies the default duration for historical data retrieval. Must be integer ≥ 0 and ≤ maxDuration.
defaultDuration.unit
optional
enumSpecifies the unit for the default duration of historical data retrieval. Accepted values: Minute | Hour | Day.
  1. Apply your YAML definition using the sloctl apply command.
  2. Deploy your agent in a Kubernetes cluster or Docker container.

Important notes:

  • ServiceNow Cloud Observability requires the name of organization registered in ServiceNow Cloud Observability, the name of the project, and the appToken. Refer to the Authentication section for more details.

  • spec.historicalDataRetrieval - refer to Replay documentation for more details.

  • You can update the lightstep.url with sloctl or Nobl9 Terraform provider.

Querying the ServiceNow Cloud Observability API​

The Nobl9 agent makes calls the ServiceNow Cloud Observability API once every 60 seconds.

API rate limits​

ServiceNow Cloud Observability has low rate limits for its Streams Timeseries API. For Community, Professional, and Enterprise licenses it’s 60, 200, 600 requests per hour respectively. The Nobl9 agent makes requests once every 60s, which allows for one ServiceNow Cloud Observability organization to use only 1, 3, or 10 unique metric specifications. For more information, refer to the Rate Limits | ServiceNow Cloud Observability documentation.

ServiceNow Cloud Observability users can request an increase of rate limits via ServiceNow Cloud Observability customer support.

For a more in-depth look, consult additional resources:
Monitor Metric DataServiceNow Cloud Observability docsInvestigate a Latency RegressionServiceNow Cloud Observability docsInvestigate an Error Rate IncreaseServiceNow Cloud Observability docsInvestigate a Metric DeviationServiceNow Cloud Observability docsCreate and Manage API KeysServiceNow Cloud Observability docsStreams TimeseriesServiceNow Cloud Observability docsQuery TimeseriesServiceNow Cloud Observability docsRate LimitsServiceNow Cloud Observability docsUnified Query Language (UQL)ServiceNow Cloud Observability docsMetric KindsServiceNow Cloud Observability docsUsing distributions in UQLServiceNow Cloud Observability docsAgent metricsNobl9 agentCreating SLOs via TerraformThe Nobl9 Terraform provider docsCreating agents via TerraformThe Nobl9 Terraform provider docs
Last updated on
On this page