Sumo Logic metrics handlers reference

COMMERCIAL FEATURE: Access Sumo Logic metrics handlers in the packaged Sensu Go distribution. For more information, read Get started with commercial features.

Sensu executes Sumo Logic metrics handlers during the process stage of the observability pipeline.

Sumo Logic metrics handlers provide a persistent connection to transmit Sensu observability metrics to a Sumo Logic HTTP Logs and Metrics Source, which helps prevent the data bottlenecks you may experience with traditional handlers.

Traditional handlers start a new UNIX process for every Sensu event they receive and require a new connection to send every event. As you scale up and process more events per second, the rate at which the handler can transmit observability event data decreases.

Sumo Logic metrics handlers allow you to configure a connection pool with a maximum number of connections for the handler to use and a time limit for request completion. For example, if 1000 events are queued for transmission, as each connection finishes transmitting an event, it becomes available again and returns to the pool so the handler can use it to send the next event in the queue.

Sumo Logic metrics handlers will reuse the available connections as long as they can rather than requiring a new connection for every event, which increases event throughput.

NOTE: Sumo Logic metrics handlers only accept metrics events. To send status events, use the Sensu Sumo Logic Handler integration instead.

Sumo Logic metrics handler examples

This example shows a Sumo Logic metrics handler resource definition configured to send Sensu observability data to a Sumo Logic HTTP Logs and Metrics Source via the url attribute:

---
type: SumoLogicMetricsHandler
api_version: pipeline/v1
metadata:
  name: sumologic_http_log_metrics
spec:
  url: "https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx"
  max_connections: 10
  timeout: 30s
{
  "type": "SumoLogicMetricsHandler",
  "api_version": "pipeline/v1",
  "metadata": {
    "name": "sumologic_http_log_metrics"
  },
  "spec": {
    "url": "https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx",
    "max_connections": 10,
    "timeout": "30s"
  }
}

You can also use secrets management to avoid exposing the URL in your Sumo Logic metrics handler configuration:

---
type: SumoLogicMetricsHandler
api_version: pipeline/v1
metadata:
  name: sumologic_http_log_metrics
spec:
  url: $SUMO_LOGIC_SOURCE_URL
  secrets:
  - name: SUMO_LOGIC_SOURCE_URL
    secret: sumologic_metrics_us2
  max_connections: 10
  timeout: 30s
{
  "type": "SumoLogicMetricsHandler",
  "api_version": "pipeline/v1",
  "metadata": {
    "name": "sumologic_http_log_metrics"
  },
  "spec": {
    "url": "$SUMO_LOGIC_SOURCE_URL",
    "secrets": [
      {
        "name": "SUMO_LOGIC_SOURCE_URL",
        "secret": "sumologic_metrics_us2"
      }
    ],
    "max_connections": 10,
    "timeout": "30s"
  }
}

Use Sumo Logic metrics handlers

Sumo Logic metrics handlers are commercial resources and are available for use only in pipelines.

NOTE: Sumo Logic metrics handlers are not used by listing the handler name in the check handlers attribute.

To use a Sumo Logic metrics handler, list it as the handler in a pipeline definition. For example, this pipeline definition uses the sumologic_http_log_metrics example along with the built-in has_metrics event filter:

---
type: Pipeline
api_version: core/v2
metadata:
  name: metrics_workflows
spec:
  workflows:
  - name: metrics_to_sumologic
    filters:
    - name: has_metrics
      type: EventFilter
      api_version: core/v2
    handler:
      name: sumologic_http_log_metrics
      type: SumoLogicMetricsHandler
      api_version: pipeline/v1
{
  "type": "Pipeline",
  "api_version": "core/v2",
  "metadata": {
    "name": "metrics_workflows"
  },
  "spec": {
    "workflows": [
      {
        "name": "metrics_to_sumologic",
        "filters": [
          {
            "name": "has_metrics",
            "type": "EventFilter",
            "api_version": "core/v2"
          }
        ],
        "handler": {
          "name": "sumologic_http_log_metrics",
          "type": "SumoLogicMetricsHandler",
          "api_version": "pipeline/v1"
        }
      }
    ]
  }
}

Sumo Logic metrics handler specification

Top-level attributes

type
description Top-level attribute that specifies the sensuctl create resource type. Sumo Logic metrics handlers should always be type SumoLogicMetricsHandler.
required Required for Sumo Logic metrics handler definitions in wrapped-json or yaml format for use with sensuctl create.
type String
example 
type: SumoLogicMetricsHandler
{
  "type": "SumoLogicMetricsHandler"
}
api_version
description Top-level attribute that specifies the Sensu API group and version. For Sumo Logic metrics handlers in this version of Sensu, the api_version should always be pipeline/v1.
required Required for Sumo Logic metrics handler definitions in wrapped-json or yaml format for use with sensuctl create.
type String
example 
api_version: pipeline/v1
{
  "api_version": "pipeline/v1"
}
metadata
description Top-level collection of metadata about the Sumo Logic metrics handler that includes name, namespace, and created_by as well as custom labels and annotations. The metadata map is always at the top level of the handler definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. Read metadata attributes for details.
required Required for Sumo Logic metrics handler definitions in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example 
metadata:
  name: sumologic_http_log_metrics
  namespace: default
  created_by: admin
  labels:
    environment: development
    region: us-west-2
  annotations:
    managed-by: ops
{
  "metadata": {
    "name": "sumologic_http_log_metrics",
    "namespace": "default",
    "created_by": "admin",
    "labels": {
      "environment": "development",
      "region": "us-west-2"
    },
    "annotations": {
      "managed-by": "ops"
    }
  }
}
spec
description Top-level map that includes the Sumo Logic metrics handler spec attributes.
required Required for Sumo Logic metrics handler definitions in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example 
spec:
  url: $SUMO_LOGIC_SOURCE_URL
  secrets:
  - name: SUMO_LOGIC_SOURCE_URL
    secret: sumologic_metrics_us2
  max_connections: 10
  timeout: 30s
{
  "spec": {
    "url": "$SUMO_LOGIC_SOURCE_URL",
    "secrets": [
      {
        "name": "SUMO_LOGIC_SOURCE_URL",
        "secret": "sumologic_metrics_us2"
      }
    ],
    "max_connections": 10,
    "timeout": "30s"
  }
}

Metadata attributes

name
description Unique string used to identify the Sumo Logic metrics handler. Sumo Logic metrics handler names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z). Each Sumo Logic metrics handler must have a unique name within its namespace.
required true
type String
example 
name: sumologic_http_log_metrics
{
  "name": "sumologic_http_log_metrics"
}
namespace
description Sensu RBAC namespace that the Sumo Logic metrics handler belongs to.
required false
type String
default default
example 
namespace: default
{
  "namespace": "default"
}
created_by
description Username of the Sensu user who created the Sumo Logic metrics handler or last updated the Sumo Logic metrics handler. Sensu automatically populates the created_by field when the Sumo Logic metrics handler is created or updated.
required false
type String
example 
created_by: admin
{
  "created_by": "admin"
}
labels
description Custom attributes to include with observation event data that you can use for response and web UI view filtering.

If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data.

Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels.
required false
type Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string.
default null
example 
labels:
  environment: development
  region: us-west-2
{
  "labels": {
    "environment": "development",
    "region": "us-west-2"
  }
}
annotations
description Non-identifying metadata to include with observation event data that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu.

In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views.
required false
type Map of key-value pairs. Keys and values can be any valid UTF-8 string.
default null
example 
annotations:
  managed-by: ops
{
  "annotations": {
    "managed-by": "ops"
  }
}

Spec attributes

url
description The URL for the Sumo Logic HTTP Logs and Metrics Source where Sensu should transmit the observability metrics. You can also provide the URL as a secret.
required true
type String
example without secrets 
url: https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx
{
  "url": "https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx"
}
example with secrets 
url: $SUMO_LOGIC_SOURCE_URL
{
  "url": "$SUMO_LOGIC_SOURCE_URL"
}
secrets
description Array of the name/secret pairs to use with command execution. Read secrets attributes for details. You can also provide the Sumo Logic HTTP Logs and Metrics Source URL directly in the url attribute instead of configuring a secret.
required false
type String
example 
secrets:
- name: SUMO_LOGIC_SOURCE_URL
  secret: sumologic_metrics_us2
{
  "secrets": [
    {
      "name": "SUMOLOGIC_METRICS_URL",
      "secret": "sumologic_metrics_us2"
    }
  ]
}
max_connections
description Maximum number of connections to keep alive in the connection pool. If set to 0, there is no limit to the number of connections in the pool.
required false
type Integer
example 
max_connections: 10
{
  "max_connections": 10
}
timeout
description Duration to allow for processing a Sumo Logic call. In seconds.
required true
type String
example 
timeout: 10s
{
  "timeout": "10s"
}

Secrets attributes

name
description Name of the secret defined in the handler’s URL attribute. Becomes the environment variable presented to the handler. Read Use secrets management in Sensu for more information.
required true
type String
example 
name: SUMOLOGIC_METRICS_URL
{
  "name": "SUMOLOGIC_METRICS_URL"
}
secret
description Name of the Sensu secret resource that defines how to retrieve the secret.
required true
type String
example 
secret: sumologic_metrics_us2
{
  "secret": "sumologic_metrics_us2"
}