This guide provides an overview and setup instructions for Middleware’s OpenTelemetry Data Ingestion API. The OpenTelemetry Ingestion API has two endpoints: Metrics and Logs.

Resource Types

For both endpoints, the resource type attribute groups the ingested data under the specified label on Middleware dashboards and reports. The resource type field requires one of the following options.

GroupResource Type
hosthost.id
k8s.nodek8s.node.uid
k8s.podk8s.pod.uid
k8s.deploymentk8s.deployment.uid
k8s.daemonsetk8s.daemonset.uid
k8s.replicasetk8s.replicaset.uid
k8s.statefulsetk8s.statefulset.uid
k8s.namespacek8s.namespace.uid
serviceservice.name
osos.type
customcustom

Metrics Endpoint

The Metrics endpoint lets you send custom metrics to the Middleware backend.

To send custom metrics to Middleware, POST to the following endpoint.

POST
POST https://<UID>.middleware.io/v1/metrics

View the following example of a curl request sending a custom metric, swap-usage, to Middleware.

Shell
curl -X POST "https://demo.middleware.io/v1/metrics" \
-H "Accept: application.json" \
-H "Content-type: application.json" \
-d @ << EOF
{
    "resource_metrics": [
        {
            "resource": {
                "attributes": [
                    {
                        "key": "mw.account_key",
                        "value": {
                            "string_value": "xxxxxxxxxx"
                        }
                    },
                    {
                        "key": "mw.resource_type",
                        "value": {
                            "string_value": "custom"
                        }
                    }
                ]
            },
            "scope_metrics": [
                {
                    "metrics": [
                        {
                            "name": "swap-usage",
                            "description": "SWAP Usage",
                            "unit": "bytes",
                            "gauge": {
                                "data_points": [
                                    {
                                        "attributes": [
                                            {
                                                "key": "device",
                                                "value": {
                                                    "string_value": "nvme0n1p4"
                                                }
                                            }
                                        ],
                                        "start_time_unix_nano": 1673435153000000000,
                                        "time_unix_nano": 1673435153000000000,
                                        "asInt": 400500678
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}
EOF  
Data must be in OTLP/HTTP format. Learn more about OTLP/HTTP.

Resource Attributes

FieldRequiredDescription
mw.account_keyAuthenticates into your Middleware Account
mw.resource_typeGroups and labels the metric, see Resource Types for allowed values

Metrics

There are two components for Metrics: metadata and datapoint

Metadata

The metadata fields are the request body attributes that define the metric and determine how it will appear in Middleware.

Metadata FieldRequiredDescription
nameDefines the metric name
description✖️Additional details about the metric
unit✖️Identifies the measurement type

Datapoint

The datapoint fields are defined within the data attribute. The datapoint fields are consistent across all data attribute types, and explained below. The data attribute is named one of the following types:

  • Gauge: A scalar metric that always exports the current value for every data point. It should be used for unknown aggregation.
  • Sum: A scalar metric that is calculated as a sum of all reported measurements over a time interval.
  • Histogram: A metric that is calculated by aggregating as a histogram of all reported measurements over a time interval.
  • Exponential Histogram: A metric that is calculated by aggregating as an exponential histogram of all reported double measurements over a time interval.
  • Summary: Metric data used to convey quantile summaries.
Datapoint FieldRequiredDescription
attributesKey-value pairs associated with the data point
time_unix_nanoSet to the end time of the aggregation
start_time_unix_nano✖️Indicates the start time, should be included whenever possible

Log Endpoint

The Log Endpoint lets you send custom logs to the Middleware backend.

To send custom logs to Middleware, POST to the following endpoint.

POST
POST https://<UID>.middleware.io:443/v1/logs

View the following example of a curl request sending custom logs to Middleware.

Shell
curl -X POST "https://demo.middleware.io:443/v1/logs" \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-d @- << EOF
{
   "resource_logs": [
      {
         "resource": {
            "attributes": [
               {
                  "key": "mw.account_key",
                  "value": {
                     "string_value": "xxxxxxxxxx"
                  }
               },
               {
                  "key": "mw.resource_type",
                  "value": {
                     "string_value": "custom"
                  }
               },
               {
                  "key": "service_name",
                  "value": {
                     "string_value": "nginx-123"
                  }
               }
            ]
         },
         "scope_logs": [
            {
               "log_records": [
                  {
                     "severity_text": "WARN",
                     "body": {
                        "string_value": "upstream server not accepting request"
                     },
                     "severity_number": "11",
                     "attributes": [
                        {
                           "key": "server",
                           "value": {
                              "string_value": "nginx"
                           }
                        }
                     ],
                     "time_unix_nano": "1694030143000"
                  }
               ]
            }
         ]
      }
   ]
}
EOF   

Resource Attributes

FieldRequiredDescription
mw.account_keyAuthenticates into your Middleware Account
mw.resource_typeGroups and labels the log source, see Resource Types for allowed values
service_name✖️Additional parameter to identify and filter logs

Log Records

FieldRequiredDescription
severity_text✖️Labels log severity (string), requires one of FATAL, ERROR, WARN, INFO, DEBUG, TRACE
severity_number✖️Labels log severity (integer), number must be between 1 and 24
bodyThe actual log body to ingest
time_unix_nanoSets a timestamp for the log

severity_number

SeverityMessage
1-4TRACE
5-8DEBUG
9-12INFO
13-16WARN
17-20ERROR
21-24FATAL
Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.