Skip to main content

Sumo Logic

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

Sumo Logic is an observability platform that provides visibility into AWS, Azure, and GCP cloud applications and infrastructure.

Authentication​

Access ID & access key​

Nobl9 leverages the Search Job API | Sumo Logic documentation to call the Sumo Logic server.

To connect to Sumo Logic, you need to provide Access ID and Access Key when creating your data source in Nobl9 UI to authenticate with Sumo Logic API. Refer to Sumo Logic documentation for details on how to get your access ID and access key.

Note that Nobl9 only supports the <accessId>:<accessKey> authentication method described in the General API Information | Sumo Logic documentation.

caution

Currently, Nobl9 integration with Sumo Logic does not support Base64 encoded Access ID for authentication.

Service endpoint URL​

Sumo Logic provides multiple API endpoints. These endpoints are assigned to the specific deployment. They depend on (1) your geographic location and (2) your account’s creation date.

Nobl9 cannot determine that value automatically, and because of that, you need to specify the correct Service Endpoint URL to connect to Sumo Logic. You can see the Service Endpoint URL when you log in to your Sumo Logic account.

For the full overview of service URLs and how they correspond to API endpoints, refer to the Sumo Logic Endpoints | Sumo Logic documentation.

Adding Sumo Logic as a data source​

To ensure data transmission between Nobl9 and your data source, it may be necessary to list Nobl9 IP addresses as trusted.

IP addresses to add to your allowlist:
  • 18.159.114.21
  • 18.158.132.186
  • 3.64.154.26
⚠ Applies to app.nobl9.com only. In all other cases, contact Nobl9 support.

You can add the Sumo Logic data source using the direct or agent connection methods. For both methods, start with these steps:

  1. Navigate to Integrations > Sources.
  2. Click .
  3. Click the relevant Source icon.
  4. Choose a relevant connection method (Agent or Direct), then configure the source as described below.

Sumo Logic direct​

Direct configuration in the UI​

Direct connection to Sumo Logic requires users to enter their credentials which Nobl9 stores safely.

  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 may be subject to change.

  2. Enter the Service Endpoint URL (mandatory).
    Sumo Logic provides multiple API endpoints that are assigned to a specific deployment. These endpoints depend on your geographic location and the creation date of your account. Refer to the Sumo Logic API Endpoints for more details. Example Service Endpoint URL: https://service.sumologic.com

  3. Enter your Access ID (mandatory).
    Refer to the Authentication section above for details.

  4. Enter your Access key (mandatory).
    Refer to the Authentication section above for details.

  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 Sumo Logic integration for Query delay is 4 minutes.
    info
    Changing the Query delay may affect your SLI data. For more details, check the Query delay documentation.
  6. Click Add Data Source.

Direct using CLI - YAML​

The YAML for setting up a direct connection to Sumo Logic looks like this:

apiVersion: n9/v1alpha
kind: Direct
metadata:
  name: sumologic-direct
  displayName: Sumo Logic Direct
  project: default
spec:
  description: Direct settings for sumologic datasource
  sourceOf:
  - Metrics
  - Services
  sumologic:
    url: https://service.sumologic.com
    access-id: #secret
    access-key: #secret
  queryDelay:
      unit: Minute # string, one of: Second || Minute
      value: 720 # numeric, must be a number less than 1440 minutes (24 hours)
  logCollectionEnabled: false # boolean, defaults to 'false'. Set to true if you'd like your source to collect logs. It's a beta functionality available only through direct release channel. Reach out to support@nobl9.com to activate it.
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. Beta functionality available only through direct release channel. Reach out to support@nobl9.com to activate it.
releaseChannel
mandatory
enumSpecifies the release channel. Accepted values: beta | stable.
Source-specific fields
sumologic.url
mandatory
stringService endpoint. See authentication for more details.
sumologic.access-id
mandatory
string, secretUsed to authenticate with Sumo Logic API. See authentication for more details.
sumologic.access-key
mandatory
stringUsed to authenticate with Sumo Logic API. Service endpoint. See authentication for more details.

Sumo Logic agent​

Agent configuration in the UI​

Follow the instructions below to create your Sumo Logic agent connection. Refer to the section above for the descriptions of the fields.

  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 may be subject to change.

  2. Enter the Service Endpoint URL (mandatory).

  1. Enter a Project.
  2. Enter a Display Name.
  3. Enter a Name.
  4. Create a Description.
  5. Customize the Query Delay.
  6. Click Add Data Source.

Agent using CLI - YAML​

The YAML for setting up an agent connection to Sumo Logic looks like this:

apiVersion: n9/v1alpha
kind: Agent
metadata:
  name: sumologic-agent
  displayName: Sumo Logic Agent # optional
  project: default
spec:
  description: Agent settings for sumologic datasource # optional
  sourceOf:
    - Metrics
    - Services
  releaseChannel: beta # string, one of: beta || stable
  queryDelay:
      unit: Minute # string, one of: Second || Minute
      value: 720 # numeric, must be a number less than 1440 minutes (24 hours)
  sumologic:
    url: https://service.sumologic.com
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
sumologic.url
mandatory
stringService endpoint. See authentication section above for more details.
warning

You can deploy only one agent in one YAML file by using the sloctl apply command.

Deploying Sumo Logic agent​

When you add the data source, Nobl9 automatically generates a Kubernetes configuration and a Docker command line for you to use to deploy the agent. Both of these are available in the web UI, under the Agent Configuration section. Be sure to swap in your credentials (e.g., replace <SUMOLOGIC_ACCESS_ID> and <SUMOLOGIC_ACCESS_KEY> with your organization credentials).

If you use Kubernetes, you can apply the supplied YAML config file to a Kubernetes cluster to deploy the agent. It will look something like this:

# DISCLAIMER: This deployment description contains only the fields necessary for the purpose of this demo.
# It is not a ready-to-apply k8s deployment description, and the client_id and client_secret are only exemplary values.

apiVersion: v1
kind: Secret
metadata:
  name: nobl9-agent-myorg-myproject-sumologicagent
  namespace: default
type: Opaque
stringData:
  sumologic_access_id: <SUMOLOGIC_ACCESS_ID>
  sumologic_access_key: <SUMOLOGIC_ACCESS_KEY>
  client_id: "unique_client_id"
  client_secret: "unique_client_secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nobl9-agent-myorg-myproject-sumologicagent
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      nobl9-agent-name: sumologicagent
      nobl9-agent-project: myproject
      nobl9-agent-organization: myorg
  template:
    metadata:
      labels:
        nobl9-agent-name: sumologicagent
        nobl9-agent-project: myproject
        nobl9-agent-organization: myorg
    spec:
      containers:
        - name: agent-container
          image: nobl9/agent:0.73.2
          resources:
            requests:
              memory: "350Mi"
              cpu: "0.1"
          env:
            - name: N9_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  key: client_id
                  name: nobl9-agent-myorg-myproject-sumologicagent
            - name: SUMOLOGIC_ACCESS_ID
              valueFrom:
                secretKeyRef:
                  key: sumologic_access_id
                  name: nobl9-agent-myorg-myproject-sumologicagent
            - name: SUMOLOGIC_ACCESS_KEY
              valueFrom:
                secretKeyRef:
                  key: sumologic_access_key
                  name: nobl9-agent-myorg-myproject-sumologicagent
            # The N9_METRICS_PORT is a variable specifying the port to which the /metrics and /health endpoints are exposed.
            # The 9090 is the default value and can be changed.
            # If you don’t want the metrics to be exposed, comment out or delete the N9_METRICS_PORT variable.
            - name: N9_METRICS_PORT
              value: "9090"

Creating SLOs with Sumo Logic​

Sumo Logic allows you to create SLOs for both types of metrics by:

  • Entering logs

  • Entering metrics

See the instructions in the following sections for more details.

Creating SLOs in the UI​

Follow the instructions below to create Sumo Logic threshold metric using the Metrics type:

  1. Navigate to Service Level Objectives.
  2. Click the plus button button.
  3. In step 1 of the SLO wizard, select the Service the SLO will be associated with.
  4. In step 2, select Sumo Logic as the data source for your SLO, then specify the Metric.
  5. Select Threshold metric > Metrics.
  6. Select value and units for Quantization.
    • In Sumo Logic, quantization is the process of aggregating metric data points for time series over an interval of time. The minimum value for this field is 15s.
    • For more details, refer to the Sumo Logic documentation.
  7. Select value for Rollup. Rollup is an aggregation function Sumo Logic uses when quantizing metrics.
    • Select one of the following values: avg, sum, min, max, count, none.
    • Default value is none.
  8. Enter a Query.
    • Sample query for Sumo Logic Threshold metric (Metrics type):metric=CPU_usage.
  9. In step 3, define a Time Window for the SLO.
  10. In step 4, specify the Error Budget Calculation Method and your Objective(s).
  11. In step 5, add a Name, Description, and other details about your SLO. You can also select Alert policies and Labels on this screen.
  12. When you’re done, click Create SLO.
SLI values for good and total
When choosing the query for the ratio SLI (countMetrics), keep in mind that the values ​​resulting from that query for both good and total:
  • Must be positive.
  • While we recommend using integers, fractions are also acceptable.
    • If using fractions, we recommend them to be larger than 1e-4 = 0.0001.
  • Shouldn't be larger than 1e+20.

SLOs using Sumo Logic - YAML samples​

Sumo Logic SLOs - metrics​

Here’s an example of Sumo Logic logs SLO using rawMetric (threshold metric):

apiVersion: n9/v1alpha
kind: SLO
metadata:
  name: sumologic-slo
  displayName: SumoLogic slo
  project: sumologic
spec:
  description: sumologic description
  service: sumologic-service
  indicator:
    metricSource:
      name: sumologic
    rawMetric:
      sumologic:
        type: metrics
        rollup: Avg
        quantization: 15s
        query: metric=CPU_Usage

Mandatory requirements for Sumo Logic metrics SLOs

Specification for Sumo Logic metrics has the following mandatory fields:

  • sumologic

    • type - string field. Select only one of the following values: metrics or logs.

    • quantization - integer field for the period of data aggregation.

      • In Sumo Logic, quantization is the process of aggregating metric data points for time series over an interval of time (e.g, s, h). The minimum value for this field is 15s.

      • For more details, refer to the Metric Quantization | Sumo Logic documentation.

    • rollup - string field.
      Rollup is an aggregation function Sumo Logic uses when quantizing metrics. Choose one of the below values (default is none):

    • query - string field.
      Your custom query. Example: metric=CPU_usage

Sumo Logic SLOs - logs​

Here’s an example of Sumo Logic logs SLO using rawMetric (threshold metric):

apiVersion: n9/v1alpha
kind: SLO
metadata:
  name: sumologic-slo
  displayName: SumoLogic slo
  project: sumologic
spec:
  description: sumologic description
  service: sumologic-service
  indicator:
    metricSource:
      name: sumologic
    rawMetric:
      sumologic:
        type: logs
        query: |
          _sourceCategory=uploads/nginx
          | timeslice 1m as n9_time
          | parse "HTTP/1.1\" * * *" as (status_code, size, tail)
          | if (status_code matches "20*" or status_code matches "30*",1,0) as resp_ok
          | sum(resp_ok) as n9_value by n9_time
          | sort by n9_time asc

Mandatory requirements for Sumo Logic Logs queries

  • query:

    • Must contain the keyword timeslice:

      • Sumo Logic supports only integers (15s , 1m, 1050ms).

      • The minimum value for timeslice is 15 sec.

    • Must contain n9time and n9value: The n9time is the actual time, and the n9value is the metric value. The n9time must be a Unix timestamp and the n9value must be a float value.

    • Must contain aggregation keyword, such as count(*) by n9_time as n9_value.

    • Alias fields or your query by an as operator to ensure you get an n9_time and n9_value returned in your query. For details on the as operator, refer to Sumo Logic documentation.

For more details on constructing Sumo Logic queries, see the Querying for logs section below.

Querying for logs​

Sumo Logic Search Syntax is based on Pipelines. Queries work similarly to Pipelines in Unix-like operating systems:

operator1 | operator2 | operator3

Each operator is separated by the | sign and passes the result to the next one, and they are progressively filtered, so eventually, you get the desired result.

All queries begin with a keyword or string search. Special characters:

  • * - a wildcard, for zero or more characters.

  • ? - a question Mark, for a single character.

An example of Sumo Logic query looks like this:

_sourceCategory=uploads/nginx
| parse "HTTP/1.1\" * * *" as (status_code, size, tail)

In the example above, the first wildcard is evaluated as the status_code, the second - size, and the third will store the remaining message.

An example good query for count metrics (SLO based on HTTP status codes) looks like this:

_sourceCategory=uploads/nginx
| timeslice 1m as n9_time
| parse "HTTP/1.1\" * * *" as (status_code, size, tail)
| if (status_code matches "20*" or status_code matches "30*",1,0) as resp_ok
| sum(resp_ok) as n9_value by n9_time
| sort by n9_time asc

That will produce the following output:

"n9_time","n9_value"
"1645371960000","2.0"
"1645372020000","58.0"
"1645372080000","46.0"
"1645372140000","12.0"
"1645372200000","12.0"
"1645372260000","12.0"
"1645372320000","14.0"
"1645372380000","22.0"

A similar query, but for Total instead of Good:

_sourceCategory=uploads/nginx
| timeslice 1m as n9_time
| parse "HTTP/1.1\" * * *" as (status_code, size, tail)
| count(*) as n9_value by n9_time
| sort by n9_time asc

For the full specification on Sumo Logic queries, refer to the official documentation.

Querying the Sumo Logic​

Nobl9 queries Sumo Logic leveraging the Search Job API or Metrics Query API every two minutes with a query delay of four minutes. The maximum resolution of the response must be 4 data points.

The query's Time range is set from the beginning and end of the 2-minute-time window being queried.

Sumo Logic API rate limits​

Sumo Logic's Search Job API requests are rate limited (see Rate limit throttling | Sumo Logic documentation).

The Nobl9 agent requests several endpoints to gather data points according to the Process Flow described in the documentation. The Nobl9 agent distributes the required requests within the two-minute interval to reduce the number of requests per second.

To prevent Sumo Logic rate limits issues:

  • Prefer metrics queries over logs queries. Logs are at least 4 times more expensive than metrics (see how to convert your logs to metrics)
  • Logs queries should take at most two minutes (using Sumo Logic partitions and Sumo Logic scheduled views will help a lot)
  • If you're using the Nobl9 agent for Sumo Logic, stick to a single agent as your data source (this will allow Nobl9 to orchestrate querying Sumo Logic API). This does not apply to directs, having multiple of them doesn't impact rate limiting orchestration.
  • Keep the number of Sumo Logic logs objectives in check with your API limits (see Number of objectives directed)
  • Contact Sumo Logic customer support to increase your rate limits and prevent conflicts.

Number of directed objectives​

Sumo Logic allows for a total of 240 requests per minute to its APIs combined. Nobl9 agent for Sumo Logic has a 2-minute query interval. It means that Nobl9 can make up to 480 API requests to Sumo Logic.

Querying for metrics​

Querying metrics is synchronous—you query, and the API responds with data.

This means you could have at most 480 unique Metrics queries run against Sumo Logic API.

Querying for logs​

Querying logs is more complicated. The following shows the lifecycle of obtaining the data:

  1. Create a search logs job.
  2. Wait 20 seconds and query if the job is completed (repeat until the process is completed).
  3. Fetch data for the finished job.
  4. Delete the job.

Each of the steps executed uses up one request to the Sumo Logic API. The optimistic count for a single logs query is 4. Step 2 (listed above) may, and most probably will, be repeated, as logs queries usually need more processing time. The pessimistic count is that step 2. will be repeated 6 times using up to 9 API requests per a single logs query.

This means that you can have anywhere from 54 to 120 logs queries.

Limitations​

For direct connections, we only support orchestration of querying Sumo Logic within the same release channel. Having the direct connections both in the Stable and Beta release channels causes desynchronization of querying and may result in failures.

API Authentication | Sumo Logic documentation

API Keys | Sumo Logic documentation

'as' Operator | Sumo Logic documentation

Metric Quantization | Sumo Logic documentation

Rate limit throttling | Sumo Logic documentation

Process Flow | Sumo Logic documentation

Agent metrics

Creating SLOs via Terraform

Creating agents via Terraform

Last updated on
On this page