Graphite
Graphite is a monitoring tool used to track the performance of websites, applications, business services, and networked servers.
Scope of Support
Currently, Nobl9 integration with Graphite does not support the Direct connection.
Authentication
Graphite does not directly support authentication for connections to its HTTP API. Organizations can set it in their infrastructure. Nobl9 connects to Graphite through the Render URL API. To connect Nobl9 Agent to Graphite, you must specify your Render URL API endpoint that allows you to generate graphs and retrieve raw data from Graphite. For more details, see The Render URL API | Graphite Documentation.
Optional Bearer Token
If GRAPHITE_AUTH_BEARER_TOKEN
variable is set during agent startup, its value will be added as an Authorization header to every HTTP request.
Optional HTTP Basic Authentication Credentials
This plugin allows credentials passed as environment variables during agent startup. The keys are GRAPHITE_BASIC_AUTH_USERNAME
and GRAPHITE_BASIC_AUTH_PASSWORD
.
Adding Graphite as a Data Source in the UI
To add Graphite as a data source in Nobl9 using the Agent connection method, follow these steps:
- Navigate to Integrations > Sources.
- Click the
button.
- Click the relevant Source icon.
- Choose a relevant connection method (Agent or Direct), then configure the source as described below.
Graphite Agent
Agent Configuration in the UI
Follow the instructions below to configure your Graphite Agent:
- 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 abeta
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.
- The
Enter the Render URL API to connect to your data source.
The URL must start withhttp://
orhttps://
.
- 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 then object is assigned to projectdefault
. - Enter a Display Name.
You can enter a friendly name with spaces in this field. - Enter a Name.
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.
Here you can add details such as who is responsible for the integration (team/owner) and the purpose of creating it. - Customize the Query delay to set a customized delay for queries when pulling the data from the data source.
- The default value in Graphite integration for Query delay is
1 minute
.
infoChanging the Query delay may affect your SLI data. For more details, check the Query delay documentation. - The default value in Graphite integration for Query delay is
- Enter a Maximum Period for Historical Data Retrieval.
- This value defines how far back in the past your data will be retrieved.
- The value for the Maximum period of data retrieval depends on the Source. Check the Replay documentation for details.
- Entering a more extended Period might slow down the loading time when creating an SLO.
- The value must be a positive integer.
- Enter a Default Period for Historical Data Retrieval.
- It is the Period that will be used by the SLO connected to this data source.
- The value must be a positive integer or
0
. - By default, this value is set to 0. If you set it to
>0
, you will create an SLO with Replay.
- Click the Add Data Source
Since Graphite is based on user settings, make sure Replay is aligned with the settings applied in the storage-schemas.conf
and storage-aggregation.conf
configuration files.
Agent Using CLI - YAML
The YAML for setting up an Agent connection to Graphite looks like this:
apiVersion: n9/v1alpha
kind: Agent
metadata:
name: Graphite
displayName: Graphite # optional
project: Graphite Agent
spec:
description: Agent settings for Graphite # 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)
graphite:
url: http://graphite.datasource-example/render
historicalDataRetrieval:
maxDuration:
value: 30 # integer greater than or equal to 0
unit: Day # accepted values: Minute, Hour, Day
defaultDuration: # value must be less than or equal to value of maxDuration
value: 0 # integer greater than or equal to 0
unit: Day # accepted values: Minute, Hour, Day
Important notes:
url
: string render API URL endpoint of Graphite's instance. For more details, refer to the Authentication section above.spec[n].historicalDataRetrieval
- refer to Replay Documentation | Nobl9 Documentation for more details.
You can deploy only one Agent in one YAML file by using the sloctl apply
command.
Deploying Graphite 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.
- 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-graphite-secret
namespace: default
type: Opaque
stringData:
client_id: "unique_client_id"
client_secret: "unique_client_secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: nobl9-agent-graphite-deployment
namespace: default
spec:
replicas: 1
selector:
matchLabels:
nobl9-agent-name: "graphite-name"
nobl9-agent-project: "graphite"
nobl9-agent-organization: "organization"
template:
metadata:
labels:
nobl9-agent-name: "graphite-name"
nobl9-agent-project: "graphite"
nobl9-agent-organization: "organization"
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-graphite-secret
- name: N9_CLIENT_SECRET
valueFrom:
secretKeyRef:
key: client_secret
name: nobl9-agent-graphite-secret
# 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"
If you use Docker, you can run the Docker command to deploy the Agent. It will look something like this:
# DISCLAIMER: This docker command description is containing only the necessary fields for the purpose of this demo.
# It is not a ready-to-apply docker command.
docker run -d --restart on-failure \
--name nobl9-agent-graphite-container \
-e N9_CLIENT_ID="unique_client_id" \
-e N9_CLIENT_SECRET="unique_client_secret" \
# 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.
-e N9_METRICS_PORT=9090 \
nobl9/agent:latest
Creating SLOs with Graphite
Creating SLOs in the UI
Follow the instructions below to create your SLOs with Graphite in the UI:
Navigate to Service Level Objectives.
- Click the
button.
In step 2, select Graphite as the Data Source for your SLO, then specify the Metric. You can choose either a Threshold Metric, where a single time series is evaluated against a threshold, or a Ratio Metric, which allows you to enter two time series to compare (for example, a count of good requests and total requests).
noteFor the Ratio Metric, you can choose the Data Count Method:
- For the Non-incremental method, we expect it to be the components of the sum.
- For the Incremental method, we expect the value of a metric to be the current sum of some numerator.
For more information, refer to the SLO Calculations Guide.
Enter a Query or Good Query, and Total Query for the metric you selected. The following are query examples:
Threshold metric for Graphite:
Query:carbon.agents.9b365cce.cpuUsage
Ratio metric for Graphite:
Good Query:stats_counts.response.200
Total Query:astats_counts.response.all
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.
SLOs with Graphite - YAML samples
- rawMetric
- countMetric
Here’s an example of Graphite using a rawMetric
(Threshold metric):
apiVersion: n9/v1alpha
kind: SLO
metadata:
name: graphite-slo-1
project: graphite
spec:
service: web-service
indicator:
metricSource:
name: graphite-agent
timeWindows:
- unit: Day
count: 7
isRolling: true
budgetingMethod: Occurrences
objectives:
- displayName: Good
op: lte
rawMetric:
query:
graphite:
metricPath: carbon.agents.9b365cce.cpuUsage
value: 100
target: 0.9
Here’s an example of Graphite using a countMetric
(Ratio metric):
apiVersion: n9/v1alpha
kind: SLO
metadata:
name: graphite-slo-2
project: default
spec:
service: web-service
indicator:
metricSource:
name: graphite-agent
timeWIndows:
- unit: Day
count: 7
calendar:
startTime: 2020-03-09 00:00:00
timeZone: Europe/Warsaw
budgetingMethod: Occurrences
objectives:
- displayName: Good
target: 0.95
countMetrics:
incremental: false
good:
graphite:
metricPath: stats_counts.response.200
total:
graphite:
metricPath: stats_counts.response.all
Metric specification for Graphite has only one mandatory field:
metricPath
- it is a string field that specifies Graphite’s metric path, such asservers.cpu.total
Visit the following link to understand Paths and Wildcards.
The Graphite documentation suggests using *
, [
,]
, {
, or }
, but Nobl9 does not support this functionality. When you use *
, [
,]
, {
, or }
, a validation error occurs.
Querying the Graphite Server
Metrics are retrieved using the from
and until
parameters once per minute. The API returns a half-open interval (from, until]
, which includes the end date but not the start date.
Useful Links
Paths and Wildcards | Graphite Documentation
The Render URL API | Graphite Documentation
Agent Metrics | Nobl9 Documentation
Creating SLOs via Terraform | Nobl9 Terraform Documentation
Creating Agents via Terraform | Nobl9 Terraform Documentation