Sumo Logic
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 in the UI​
To add Sumo Logic as a data source in Nobl9 using the Agent or Direct connection method, follow these steps:
Navigate to Integrations > Sources.
Click the
button.
Click the Sumo Logic icon.
Choose a configuration method (Direct or Agent), 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.
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
Enter your Access ID (mandatory).
Refer to the Authentication section above for details.Enter your Access key (mandatory).
Refer to the Authentication section above for details.Select a Project (mandatory).
Specifying the Project is helpful when multiple users are spread across multiple teams or projects. When the Project field is left blank, a default value appears.Enter a Display name (optional).
You can enter a friendly name with spaces in this field.Enter a Name (mandatory).
The name is mandatory and can only contain lowercase, alphanumeric characters, and dashes (for example,my-project-name
). This field is populated automatically when you enter a display name, but you can edit the result.Enter a Description (optional).
Here you can add details such as who is responsible for the integration (team/owner) and the purpose of creating it.Click the Add Data Source button.
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.
Enter the Service Endpoint URL (mandatory).
Select a Project (mandatory).
Enter a Display name (optional).
Enter a Name (mandatory).
Enter a Description (optional).
Click the Add Data Source button.
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).
- Kubernetes
- Docker
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: latest
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
If you use Docker, you can run the Docker command to deploy the agent. It will look something like this (be sure to swap <SUMOLOGIC_ACCESS_ID>
and <SUMOLOGIC_ACCESS_KEY>
with your organization’s credentials):
# DISCLAIMER: This Docker command contains only the fields necessary for the purpose of this demo.
# It is not a ready-to-apply command, and you will need to replace the placeholder values with your own values.
docker run -d --restart on-failure \
--name nobl9-agent-sumo-logic-test \
-e N9_CLIENT_ID="unique_client_id" \
-e N9_CLIENT_SECRET="unique_client_secret" \
-e SUMOLOGIC_ACCESS_ID="<SUMOLOGIC_ACCESS_ID>" \
-e SUMOLOGIC_ACCESS_KEY="<SUMOLOGIC_ACCESS_KEY>" \
nobl9/agent: latest;
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​
- Threshold – Metrics
- Threshold – Logs
- Ratio – Metrics
- Ratio – Logs
Follow the instructions below to create Sumo Logic Threshold metric using Metrics type:
- Navigate to Service Level Objectives.
- Click the
button.
- In step 1 of the SLO wizard, select the Service the SLO will be associated with.
- In step 2, select Sumo Logic as the Data Source for your SLO, then specify the Metric.
- Select Threshold metric > Metrics.
- 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.
- 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
. - Enter a Query.
- Sample query for Sumo Logic Threshold metric (Metrics type):
metric=CPU_usage
. - In step 3, define a Time Window for the SLO.
- In step 4, specify the Error Budget Calculation Method and your Objective(s).
- In step 5, add a Name, Description, and other details about your SLO. You can also select Alert Policies and Labels on this screen.
- When you’re done, click Create SLO.
Follow the instructions below to create Sumo Logic Threshold metric using Logs type:
- Navigate to Service Level Objectives.
- Click the
button.
- In step 1 of the SLO wizard, select the Service the SLO will be associated with.
- In step 2, select Sumo Logic as the Data Source for your SLO, then specify the Metric.
- Select Threshold metric > Logs.
- Enter a Query
- The Query must contain the keyword
timeslice
. - Sample query for Sumo Logic Threshold metric:
_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 - In step 3, define a Time Window for the SLO.
- In step 4, specify the Error Budget Calculation Method and your Objective(s).
- In step 5, add a Name, Description, and other details about your SLO. You can also select Alert Policies and Labels on this screen.
- When you’re done, click Create SLO.
Follow the instructions below to create Sumo Logic Ratio metric using Metrics type:
- Navigate to Service Level Objectives.
- Click the
button.
- In step 1 of the SLO wizard, select the Service the SLO will be associated with.
- In step 2, select Sumo Logic as the Data Source for your SLO, then specify the Metric.
- Select Ratio metric > Metrics.
- Enter a Query:
- Good query for the Ratio Metric (Metrics type):quantization: 15s
rollup: Avg
query: metric=Mem_Used - Total query for the Ratio Metric (Metrics type):quantization: 15s
rollup: Avg
query: metric=Mem_Total - In step 3, define a Time Window for the SLO.
- In step 4, specify the Error Budget Calculation Method and your Objective(s).
- In step 5, add a Name, Description, and other details about your SLO. You can also select Alert Policies and Labels on this screen.
- When you’re done, click Create SLO.
Follow the instructions below to create Sumo Logic Ratio metric using Logs type:
- Navigate to Service Level Objectives.
- Click the
button.
- In step 1 of the SLO wizard, select the Service the SLO will be associated with.
- In step 2, select Sumo Logic as the Data Source for your SLO, then specify the Metric.
- Select Ratio metric > Logs.
- Enter a Query. The query must contain the keyword
timeslice
: - Good query for the Ratio Metric (Logs type):
- Total query for the Ratio Metric (Logs type):
- In step 3, define a Time Window for the SLO.
- In step 4, specify the Error Budget Calculation Method and your Objective(s).
- In step 5, add a Name, Description, and other details about your SLO. You can also select Alert Policies and Labels on this screen.
- When you’re done, click Create SLO.
_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
_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
SLOs using Sumo Logic - YAML samples​
Sumo Logic SLOs - Metrics​
- rawMetric
- countMetric
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
Here’s an example of Sumo Logic Metrics SLO using countMetric
:
apiVersion: n9/v1alpha
kind: SLO
metadata:
name: sumologic-count
displayName: sumologic Count SLO
project: sumologic
spec:
description: sumologic Count Description
service: sumologic
indicator:
metricSource:
name: sumologic
project: sumologic
budgetingMethod: Occurrences
timeWindows:
- unit: Day
count: 7
isRolling: true
objectives:
- countMetrics: # This sample SLI determines the ratio of used memory to total memory available
incremental: false
good:
sumologic:
type: metrics
query: metric=Mem_Used
rollup: Avg
quantization: 15s
total:
sumologic:
type: metrics
query: metric=Mem_Total
rollup: Avg
quantization: 15s
displayName: ""
target: 0.9
value: 0.9
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
orlogs
.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 is15s
.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 isnone
):avg
,sum
,min
,max
,count
,none
.For more details refer to the Rollup Types | Sumo Logic Documentation.
query
- string field.
Your custom query. Example:metric=CPU_usage
Sumo Logic SLOs - Logs​
- rawMetric
- countMetric
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
Here’s an example of Sumo Logic Logs using countMetric
:
apiVersion: n9/v1alpha
kind: SLO
metadata:
name: sumologic-slo
displayName: SumoLogic slo
project: sumologic
budgetingMethod: Occurrences
timeWindows:
- unit: Day
count: 7
isRolling: true
objectives:
- countMetrics:
incremental: false
good:
sumologic:
type: logs
query: |
_sourceCategory=uploads
| 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
total:
sumologic:
type: logs
query: |
_sourceCategory=uploads/nginx
| timeslice 1m as n9_time<br/>
| parse "HTTP/1.1\" * * *" as (status_code, size, tail)
| count(*) as n9_value by n9_time
| sort by n9_time asc
displayName: ""
target: 0.9
value: 0.9
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
andn9value
: Then9time
is the actual time, and then9value
is the metric value. Then9time
must be a Unix timestamp and then9value
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 ann9_time
andn9_value
returned in your query. For details on theas
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:
*
- Wildcard, for zero or more characters.?
- 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 for building Sumo Logic query, refer to the official documentation.
Querying the Sumo Logic Server​
Nobl9 queries Sumo Logic Server leveraging the Search Job API on a per minute basis with a maximum resolution of 4 data points.
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 tries to distribute the requests needed to be done within a one-minute interval to reduce the number of requests per second.
To prevent hitting Sumo Logic Rate Limits:
- Keep the number of Sumo Logic Logs objectives low - we recommend ~20.
- Contact Sumo Logic customer support to increase your rate limits and prevent conflicts.
Useful Links​
API Authentication | Sumo Logic Documentation
API Keys | Sumo Logic Documentation
'as' Operator | Sumo Logic Documentation
Metric Quantization | Sumo Logic Documentation