dscexporter

dscexporter

A Prometheus exporter for DSC files.

Installation

To install the dscexporter, simply download the binary of the latest GitHub release and copy it to a folder of your choice, like /usr/local/bin/.

Build

The project is automatically built via GitHub Actions.
To build the project on your own, run:

make build

Usage

After installing the dscexporter to /usr/local/bin, the command dscexporter is available on your system.
To get an overview of the available flags, run:

dscexporter --help

The only required parameter is the --config parameter, which specifies the path to your config file.
To run the dscexporter as a systemd service, you can use the example service file provided.

Expected Folder Structure

The dscexporter expects the following folder structure:

<data>/<location>/<nameserver>/<timestamp>.dscdata.xml

The data folder can be set via the CLI or the config file. The exporter uses the folder names as the values for the loc and ns labels.

Config

In the config, you can configure the datasets that the dscexporter exports and the aggregations that are run on the datasets before export.
For an overview of the structure of the config, see example_config.yaml.

Timestamps

One of the most important configuration options is the timestamps setting.
The dscexporter supports exporting metrics with or without timestamps.

When timestamp export is enabled, the end time of the DSC files is used as the timestamp for the metrics.
Like aggregations or the Prometheus port, the configuration is done under the prometheus section.

Example:

prometheus:
  timestamps: true
  windowsize: 10

• timestamps: Defines whether timestamps are exported.
• windowsize: Defines how many timestamps are exported.

Aggregations

Max Cells

A simple top-k filter that removes values of the second dimension that fall outside the top x.
The removed values are added to the -:SKIPPED:- and -:SKIPPED_SUM:- cells.

Example:

second_ld_vs_rcode:
  aggregations:
    SecondLD:
      type: MaxCells
      params:
        x: 5

Eliminate Dimension

Removes the given dimension. Useful when exporting a 2D dataset where only one dimension is of interest.

Example:

qtype_vs_qnamelen:
  aggregations:
    QnameLen:
      type: EliminateDimension

This results in a dataset that only monitors the qtypes.

Filter

Filters the values of a dimension to a specified list of allowed values. All other values are summed into a other value.

Note: Each parameter is an allowed value. The colon is required for YAML, the {} are optional.

Example:

qtype:
  aggregations:
    QType:
      type: Filter
      params:
        "A": {}
        "AAAA":
        "NS":

Bucket

Exports the dataset using a histogram metric instead of the default counter metric.

Example 1 – For rcode_vs_replylen:

rcode_vs_replylen:
  aggregations:
    ReplyLen:
      type: Bucket
      params:
        start: 31
        width: 32
        count: 40

⚠️ Note: When the dataset already contains ranges like client_port_range, start, width, and count must match the dataset values. Also the _sum metric generated by histograms cannot be computed correctly because the exact values are unknown.

Other Parameters

You can also set all CLI parameters in the config file:

• remove: bool
• data: string
• interval: Duration
• prometheus.port: int

Refer to the example config file for usage.

⚠️ Important: The dscexporter does not track which files have already been exported. For production use, the remove parameter must be set to true.

Updating the Git Repository

Initial push without a tag:

git push origin refs/heads/main

Then add a tag and push it:

git tag v0.0.x
git push origin v0.0.x