Graphite

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

Graphite is a monitoring tool used to track the performance of websites, applications, business services, and networked servers.

Graphite parameters and supported features in Nobl9

General support:: Release channel: Stable, Beta; Connection method: Agent; Replay and SLI Analyzer: Supported; Event logs: Not supported; Query checker: Not supported; Query parameters retrieval: Not supported; Timestamp cache persistence: Not supported
Query parameters:: Query interval: 1 min; Query delay: 1 min; Jitter: 15 sec; Timeout: 30 sec
Agent details and minimum required versions for supported features:: Environment variable: GRAPHITE_QUERY_DELAY; Plugin name: n9graphite; Replay and SLI Analyzer: 0.65.0; Maximum historical data retrieval period: 30 days

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

You can add the Graphite data source using the agent connection method.

Nobl9 Web

Follow the instructions below to configure your Graphite agent:

Navigate to Integrations > Sources.
Click .
Click the required Source button.
Choose 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 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.
Enter the Render URL API to connect to your data source.
The URL must start with http:// or https://.

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.
Enter a Display Name.
You can enter a user-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-1). Nobl9 duplicates the display name here, transforming it into the supported format, 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.
Specify 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.
info
Changing the Query delay may affect your SLI data. For more details, check the Query delay documentation.
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.
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.
Click Add Data Source.

caution

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.

sloctl

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: stable # 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

Field	Type	Description
`queryDelay.unit` mandatory	enum	Specifies 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	numeric	Specifies 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	enum	Specifies the release channel. Accepted values: `beta` \| `stable`.
Source-specific fields
`graphiteURL` mandatory	string	Render API URL endpoint of Graphite's instance. See authentication for more details.
Replay-related fields
`historicalDataRetrieval` optional	n/a	Optional 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	numeric	Specifies 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	enum	Specifies the unit for the maximum duration of historical data retrieval. Accepted values: `Minute` \| `Hour` \| `Day`.
`defaultDuration.value` optional	numeric	Specifies the default duration for historical data retrieval. Must be integer `≥ 0` and `≤` `maxDuration`.
`defaultDuration.unit` optional	enum	Specifies the unit for the default duration of historical data retrieval. Accepted values: `Minute` \| `Hour` \| `Day`.

warning

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

Agent deployment

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:0.82.2
          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:0.82.2

Creating SLOs with Graphite

Nobl9 Web

Follow the instructions below to create your SLOs with Graphite in the UI:

Navigate to Service Level Objectives.
Click .
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).
1. Choose the Data Count Method for your ratio metric:
- Non-incremental: counts incoming metric values one-by-one. So the resulting SLO graph is pike-shaped.
- Incremental: counts the incoming metric values incrementally, adding every next value to previous values. It results in a constantly increasing SLO graph.
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
  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.
  - Shouldn't be larger than 1e+20.
In step 3, define a Time Window for the SLO.

Rolling time windows are better for tracking the recent user experience of a service.
Calendar-aligned windows are best suited for SLOs that are intended to map to business metrics measured on a calendar-aligned basis, such as every calendar month or every quarter.

In step 4, specify the Error Budget Calculation Method and your Objective(s).
- Occurrences method counts good attempts against the count of total attempts.
- Time Slicesmethod measures how many good minutes were achieved (when a system operates within defined boundaries) during a time window.
- You can define up to 12 objectives for an SLO.
See the use case example and the SLO calculations guide for more information on the error budget calculation methods.
In step 5, add the Display name, Name, and other settings for your SLO:
- Create a composite SLO
- Set notification on data, if this option is available for your data source.
  When activated, Nobl9 notifies you if your SLO hasn't received data or received incomplete data for more than 15 minutes.
- Add alert policies, labels, and links, if required.
  You can add up to 20 links per SLO.
Click Create SLO.

sloctl

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 as servers.cpu.total

Visit the following link to understand Paths and Wildcards.

caution

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.