ContextQMD
Back to Skywalking

Meter receiver

docs/en/setup/backend/backend-meter.md

11.0.05.9 KB
Original Source

Meter receiver

The meter receiver accepts the metrics of meter protocol into the meter system.

Module definition

Module definition is defined in application.yml, typically located at $SKYWALKING_BASE_DIR/config/application.yml by default.

yaml
receiver-meter:
  selector: ${SW_RECEIVER_METER:default}
  default:

In Kafka Fetcher, follow these configurations to enable it.

yaml
kafka-fetcher:
  selector: ${SW_KAFKA_FETCHER:default}
  default:
    bootstrapServers: ${SW_KAFKA_FETCHER_SERVERS:localhost:9092}

Report Meter Telemetry Data

Manual Meter API

Custom metrics may be collected by the Manual Meter API. Custom metrics collected cannot be used directly; they should be configured in the meter-analyzer-config configuration files described in the next part.

The receiver adds labels with key = service and key = instance to the collected data samples, and values from service and service instance name defined in SkyWalking Agent, for identification of the metric data.

There are following known API libs to report meter telemetry data:

Agents Bundled Meters

All following agents and components have built-in meters reporting to the OAP through Meter APIs.

  1. Go agent for Go VM metrics
  2. Python agent for PVM metrics
  3. Java agent with Spring micrometer toolkit
  4. Java agent for datasource metrics
  5. Java agent for thread-pool metrics
  6. Rover(eBPF) agent for metrics used continues profiling
  7. Satellite proxy self-observability metrics
  8. PHP agent for PHM (PHP Health Metrics) runtime metrics — Linux only (/proc sampling)
  9. Node.js agent for runtime metrics (instance_nodejs_* via MeterReportService). OAP exposes meter_instance_nodejs_* through nodejs-runtime.yaml.

Configuration file

The meter receiver is configured via a configuration file. The configuration file defines everything related to receiving from agents, as well as which rule files to load.

The OAP can load the configuration at bootstrap. If the new configuration is not well-formed, the OAP may fail to start up. The files are located at $CLASSPATH/meter-analyzer-config.

New meter-analyzer-config files is NOT enabled by default, you should make meter configuration take effect through section agent-analyzer in application.yml of skywalking backend.

yaml
 agent-analyzer:
   selector: ${SW_AGENT_ANALYZER:default}
   default:
     # ... take care of other analyzers
     meterAnalyzerActiveFiles: ${SW_METER_ANALYZER_ACTIVE_FILES:your-custom-meter-conf-without-ext-name} # The multiple files should be separated by ","

Every entry listed in meterAnalyzerActiveFiles must have a matching rule file under $CLASSPATH/meter-analyzer-config. An entry with no matching file fails the OAP startup; in previous releases such an entry was silently ignored.

Meter-analyzer-config file is written in YAML format, defined by the scheme described below. Brackets indicate that a parameter is optional.

Meters configuration

yaml
# filter the metrics, only those metrics that satisfy this condition will be passed into the `metricsRules` below.
filter: <closure> # example: '{ tags -> tags.job_name == "vm-monitoring" }'
# expPrefix is executed before the metrics executes other functions.
expPrefix: <string>
# expSuffix is appended to all expression in this file.
expSuffix: <string>
# insert metricPrefix into metric name:  <metricPrefix>_<raw_metric_name>
metricPrefix: <string>
# Optional. Declares custom layers inline, registered before the rules in this file compile,
# so that a layer referenced by `expSuffix`/`exp` needs no change in the OAP source.
layerDefinitions:
    # Layer name, must match [A-Z][A-Z0-9_]*.
  - name: <string>
    # Ordinal, unique across all layers and persisted in storage. The ordinal space is
    # partitioned by tier: 0-9999 built-in, 10000-99999 boot-time external (this file when
    # shipped on disk), 100000+ runtime rules pushed through the hot-update API.
    ordinal: <int>
    # true = services in this layer are agent-installed (default), false = conjectured.
    normal: <bool>
# Metrics rule allow you to recompute queries.
metricsRules:
  # The name of rule, which combinates with a prefix '<metricPrefix>_' as the index/table name in storage.
  # The name with prefix can also be quoted in UI (Dashboard/Template/Item/Metrics)
  name: <string>
  # MAL expression. Raw name of custom metrics collected can be used here
  exp: <string>

For more information on MAL, please refer to mal.md

rate, irate, and increase

Although we support the rate, irate, increase functions in the backend, we still recommend users to consider using client-side APIs to run these functions. The reasons are as follows:

  1. The OAP has to set up caches to calculate the values.
  2. Once the agent reconnects to another OAP instance, the time windows of rate calculation break. This leads to inaccurate results.

Runtime hot-update and debugging

Meter-analyzer-config rules are loaded through the same rule pipeline as otel-rules, so they can be added, overridden, inactivated, and reverted to the bundled content at runtime, without restarting the OAP. They can also be attached to a sampling debug session to inspect the intermediate result of every stage of a MAL expression. The catalog name to use in both APIs is meter-analyzer-config. See Runtime Rule Hot-Update API and DSL Debug API — MAL.