Prometheus Remote Write Protocol

A lightweight Java library providing Protocol Buffer definitions for the Prometheus Remote Write API specification.

This library contains only the Java protobuf classes needed to serialize and deserialize Prometheus Remote Write protocol messages, making it ideal for applications that need to interact with Prometheus remote write endpoints.

Features

• ✅ Protocol Buffer definitions for Prometheus Remote Write v1
• ✅ Minimal dependencies (only protobuf-java)
• ✅ Java 11+ compatible
• ✅ Auto-generated from official Prometheus protocol specification

Installation

Maven

<dependency>
    <groupId>com.log10x</groupId>
    <artifactId>prometheus-remote-write</artifactId>
    <version>0.1.0-alpha</version>
</dependency>

Gradle

implementation 'com.log10x:prometheus-remote-write:0.1.0-alpha'

Usage

The library provides the following protobuf message types:

• WriteRequest - The main request message containing time series data
• TimeSeries - A collection of labels and samples
• Label - A key-value pair for metric labels
• Sample - A single data point with timestamp and value

Example: Creating a Write Request

import com.log10x.prometheus.remotewrite.RemoteWrite.*;

// Create labels for the metric
Label metricName = Label.newBuilder()
    .setName("__name__")
    .setValue("my_metric")
    .build();

Label instance = Label.newBuilder()
    .setName("instance")
    .setValue("localhost:8080")
    .build();

// Create a sample with timestamp and value
Sample sample = Sample.newBuilder()
    .setValue(42.0)
    .setTimestamp(System.currentTimeMillis())
    .build();

// Create a time series
TimeSeries timeSeries = TimeSeries.newBuilder()
    .addLabels(metricName)
    .addLabels(instance)
    .addSamples(sample)
    .build();

// Create the write request
WriteRequest writeRequest = WriteRequest.newBuilder()
    .addTimeseries(timeSeries)
    .build();

// Serialize to bytes for sending over HTTP
byte[] payload = writeRequest.toByteArray();

Example: Parsing a Write Request

import com.log10x.prometheus.remotewrite.RemoteWrite.*;

// Parse from bytes
byte[] receivedData = /* ... received from HTTP request ... */;
WriteRequest request = WriteRequest.parseFrom(receivedData);

// Process the time series
for (TimeSeries ts : request.getTimeseriesList()) {
    for (Label label : ts.getLabelsList()) {
        System.out.println(label.getName() + "=" + label.getValue());
    }
    for (Sample sample : ts.getSamplesList()) {
        System.out.println("Value: " + sample.getValue() + 
                         " at " + sample.getTimestamp());
    }
}

Building from Source

Prerequisites

• JDK 11 or higher
• No IDE required (build is command-line only)

Build Commands

Generate protobuf classes and build the library:

./gradlew clean build generateProto

Generated Files

Generated Java classes are located at:

build/generated/source/proto/main/java/com/log10x/prometheus/remotewrite/

The built JAR files can be found at:

build/libs/

Protocol Specification

This library implements the Prometheus Remote Write protocol as documented at: https://prometheus.io/docs/concepts/remote_write_spec/

The protocol uses Protocol Buffers for efficient serialization and is typically sent over HTTP with Snappy compression.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Maintainer

Maintained by Dor Levi at Log10x Inc.

Links

• GitHub Repository
• Prometheus Documentation
• Remote Write Specification