The Test Data Webhook feature enables you to send data from Catchpoint to other systems for analysis. You can use templates to format the exported data as needed. This article will show you how to set up a template to format your exported test data according to the OpenTelemetry (OTel) protocol. There is a complete sample template provided at the bottom of this article. The following sections describe in detail how to set up each section of the template.
Template Sections
Three main components are critical to ensure that the OTel collector accepts and processes the template correctly. If any of these components is missing or incorrectly defined, the OTel collector will reject the template, leading to failures in collecting exporting the metrics.
The main sections are resourceMetrics, scopeMetrics, and metrics. A complete template will adhere to the following basic format:
{
"resourceMetrics": [
{
"resource": {
<details about the resource (Catchpoint environment)>
},
"scopeMetrics": [
{
"scope": {
<details about the scope>
},
"metrics": [
{
<first metric details>
},
{
<second metric details>
},
...
...
{
<last metric details>
}
]
}
]
}
]
}
Read on to learn about the data that goes in each section.
1. Resource Metrics
Resource Metrics provide context about the environment where the metrics were collected. These attributes are crucial for understanding the source of the metrics and differentiating between various instances or services.
Required Fields:
-
service.name: Identifies the service generating the metrics. In this example we are using the
${TestName}macro which will be replaced with the actual Catchpoint test name at runtime.{ "key": "service.name", "value": { "stringValue": "${TestName}" } } -
service.instance.id: Unique identifier for the instance of the service. We are using the
${nodename}macro which will be automatically replaced with the name of the node that performed the test run.{ "key": "service.instance.id", "value": { "stringValue": "${nodename}" } }
2. Scope Metrics
Scope Metrics define the scope (or context) within which the metrics were collected. This includes information about the library or application module generating the metrics.
Required Fields:
• name: Name of the instrumentation scope. You can set this value as desired.
"scope": {
"name": "catchpoint.otlp.integration",
"version": "1.0.0",
"attributes": []
}
3. Metrics
Metrics are the actual performance data collected by Catchpoint.
Mandatory Fields:
• name: Name of the metric.
"name": "api.total.timing"
• unit: Unit of measurement for the metric.
"unit": "ms"
• description: Description of the metric.
"description": "API Timing Total"
• metric type : Type of metric (gauge, counter, or histogram)
"gauge": {
• dataPoints: The values being reported, along with their attributes.
- asDouble: The value of the metric.
"asDouble": "${timingtotal}"
o Attributes: Various attributes that provide additional context about the data point. Additional attributes can be added by specifying a new key and tagging it to a Test Data Macro.
"attributes": [
{
"key": "node.name",
"value": {
"stringValue": "${nodename}"
}
},
{
"key": "test.id",
"value": {
"stringValue": "${Testid}"
}
},
{
"key": "test.name",
"value": {
"stringValue": "${Testname}"
}
},
{
"key": "test.url",
"value": {
"stringValue": "${Testurl}"
}
}
]
Metric Types
Each captured metric will fall into one of the following types:
• Gauge: Represents a single numerical value that can arbitrarily go up and down. This type applies to many of the most common measurements, including metrics such as Test Time or Connect Time.
• Counter: A cumulative metric which captures the number of times something has occurred, and therefore only increases over time. It is typically used for counting requests served, errors, etc.
• Histogram: Captures the distribution of multiple measurements. It is useful for recording things like request latencies, sizes of payloads, etc.
To use counter or histogram metrics instead of gauge, replace the gauge section with the corresponding counter or histogram section in the template.
Example Counter Metric:
{
"sum": {
"isMonotonic": true,
"aggregationTemporality": "AGGREGATION_TEMPORALITY_CUMULATIVE",
"dataPoints": [
{
"asDouble": "${totalCount}",
"timeUnixNano": "${timestamp}000000000",
"attributes": [
{
"key": "exampleKey",
"value": {
"stringValue": "${exampleValue}"
}
}
]
}
]
}
}
Example Histogram Metric:
{
"histogram": {
"dataPoints": [
{
"count": "${count}",
"sum": "${sum}",
"bucketCounts": ["${bucketCounts}"],
"explicitBounds": ["${bounds}"],
"timeUnixNano": "${timestamp}000000000",
"attributes": [
{
"key": "exampleKey",
"value": {
"stringValue": "${exampleValue}"
}
}
]
}
]
}
}
Complete Sample Template
{
"resourceMetrics": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": {
"stringValue": "${TestName}"
}
},
{
"key": "service.instance.id",
"value": {
"stringValue": "${nodename}"
}
}
]
},
"scopeMetrics": [
{
"scope": {
"name": "catchpoint.otlp.integration",
"version": "1.0.0",
"attributes": []
},
"metrics": [
{
"name": "catchpoint.total.timing",
"unit": "ms",
"description": "Timing Total",
"gauge": {
"dataPoints": [
{
"asDouble": "${timingtotal}",
"timeUnixNano": "${timestampepoch}000000000",
"attributes": [
{
"key": "node.name",
"value": {
"stringValue": "${nodename}"
}
},
{
"key": "test.id",
"value": {
"stringValue": "${Testid}"
}
},
{
"key": "test.name",
"value": {
"stringValue": "${Testname}"
}
},
{
"key": "test.url",
"value": {
"stringValue": "${Testurl}"
}
}
]
}
]
}
},
{
"name": "catchpoint.api.summary.error",
"unit": "ms",
"description": "API Summary Error",
"sum": {
"aggregationTemporality": 1,
"isMonotonic": true,
"dataPoints": [
{
"asDouble": "${if('${errorany}', 1, 0)}",
"timeUnixNano": "${timestampepoch}000000000",
"attributes": [
{
"key": "error.response",
"value": {
"stringValue": "${errorresponse}"
}
},
{
"key": "test.name",
"value": {
"stringValue": "${Testname}"
}
},
{
"key": "error.code",
"value": {
"stringValue": "${errorcode}"
}
}
]
}
]
}
},
{
"name": "catchpoint.transaction.summary.error",
"unit": "ms",
"description": "Transaction Summary Error",
"sum": {
"aggregationTemporality": 1,
"isMonotonic": true,
"dataPoints": [
{
"asDouble": "${if('${errorany}', 1, 0)}",
"timeUnixNano": "${timestampepoch}000000000",
"attributes": [
{
"key": "error.transaction",
"value": {
"stringValue": "${errortransaction}"
}
},
{
"key": "test.name",
"value": {
"stringValue": "${Testname}"
}
},
{
"key": "error.code",
"value": {
"stringValue": "${errorcode}"
}
}
]
}
]
}
}
]
}
]
}
]
}