tessl/maven-io-prometheus--simpleclient

Core instrumentation library for the Prometheus Java client, providing fundamental metric types for application monitoring

—

Pending

Overview

Eval results

Files

Info Metrics

Name: tessl/maven-io-prometheus--simpleclient
Author: tessl

Info metrics provide key-value metadata pairs for build information, version details, configuration data, and other static or semi-static information. They expose labels with a constant value of 1, making them ideal for metadata that doesn't change frequently.

Capabilities

Info Creation

Create info metrics using the builder pattern for metadata collection.

/**
 * Create a new Info builder
 * @return Builder instance for configuration
 */
public static Info.Builder build();

/**
 * Create a new Info builder with required fields
 * @param name The metric name (will have _info suffix added)
 * @param help The help text describing the metadata
 * @return Builder instance for configuration
 */
public static Info.Builder build(String name, String help);

Usage Example:

import io.prometheus.client.Info;

// Application build information
Info buildInfo = Info.build()
    .name("application_build")
    .help("Application build information")
    .register();

// Service configuration info
Info serviceConfig = Info.build()
    .name("service_config")
    .help("Service configuration metadata")
    .labelNames("service", "environment")
    .register();

Info Builder Configuration

Configure info metrics with labels and metadata structure.

public static class Builder extends SimpleCollector.Builder<Builder, Info> {
    // Note: Info metrics cannot have a unit - throws IllegalStateException
    // Inherits: name(), help(), labelNames(), namespace(), subsystem(), 
    // register(), create()
}

Important: Info metrics cannot have units. Attempting to set a unit will throw an IllegalStateException.

Info Operations

Set metadata information using key-value pairs provided as alternating strings.

/**
 * Set info metadata using alternating key-value pairs
 * @param labelPairs Even number of strings as key-value pairs
 * @throws IllegalArgumentException if odd number of strings provided
 */
public void info(String... labelPairs);

Usage Examples:

// Basic build information
buildInfo.info(
    "version", "1.2.3",
    "commit", "abc123def456", 
    "branch", "main",
    "build_time", "2024-01-15T10:30:00Z"
);

// Service configuration per environment
serviceConfig.labels("user-service", "production").info(
    "max_connections", "100",
    "timeout_seconds", "30",
    "cache_enabled", "true",
    "log_level", "INFO"
);

serviceConfig.labels("user-service", "development").info(
    "max_connections", "10", 
    "timeout_seconds", "60",
    "cache_enabled", "false",
    "log_level", "DEBUG"
);

Labeled Info Operations

Work with multi-dimensional info metrics using label values.

/**
 * Get info child for specific label values
 * @param labelValues Values for each label name (must match count)
 * @return Info.Child instance for the label combination
 * @throws IllegalArgumentException if wrong number of labels
 */
public Info.Child labels(String... labelValues);

/**
 * Remove info child for specific label values
 * @param labelValues Values identifying the child to remove
 */
public void remove(String... labelValues);

/**
 * Remove all info children
 */
public void clear();

Info Child Operations

Info.Child provides metadata operations for labeled instances.

public static class Child {
    /**
     * Set info metadata for this child using key-value pairs
     * @param labelPairs Even number of strings as alternating keys and values
     * @throws IllegalArgumentException if odd number of strings
     */
    public void info(String... labelPairs);
}

Usage Example:

// Application component information
Info componentInfo = Info.build()
    .name("component_info")
    .help("Component build and runtime information")
    .labelNames("component", "instance")
    .register();

// Set information for different components
Info.Child webComponent = componentInfo.labels("web-server", "instance-1");
webComponent.info(
    "version", "2.1.0",
    "port", "8080",
    "protocol", "HTTP/1.1",
    "worker_threads", "10"
);

Info.Child dbComponent = componentInfo.labels("database", "primary");
dbComponent.info(
    "version", "PostgreSQL 13.7",
    "max_connections", "200", 
    "shared_buffers", "256MB",
    "maintenance_work_mem", "64MB"
);

// Update info when configuration changes
webComponent.info(
    "version", "2.1.1",        // Updated version
    "port", "8080",
    "protocol", "HTTP/2",      // Updated protocol
    "worker_threads", "20"     // Updated thread count
);

Important Notes

Info Metric Naming

Info metrics automatically handle the _info suffix:

If you specify build_info as the name, it becomes build internally
When exported, it appears as build_info for Prometheus compatibility
Choose meaningful names that indicate the type of metadata

Key-Value Pair Requirements

The info() method requires an even number of strings:

Odd-positioned strings (1st, 3rd, 5th, etc.) are label names
Even-positioned strings (2nd, 4th, 6th, etc.) are label values
Must provide at least one key-value pair
Label names must follow Prometheus naming conventions

// Valid usage
info.info("key1", "value1", "key2", "value2");

// Invalid - throws IllegalArgumentException
info.info("key1", "value1", "key2"); // Missing value for key2
info.info("key1");                   // Missing value for key1

Label Naming Considerations

Use descriptive label names that clearly identify the metadata
Avoid label names that conflict with reserved Prometheus labels
Consider standardizing label names across your application
Keep label names consistent with your metrics naming conventions

Common Use Cases

// Application metadata
Info appInfo = Info.build()
    .name("application")
    .help("Application metadata")
    .register();

appInfo.info(
    "name", "user-management-service",
    "version", "3.2.1",
    "git_commit", "a1b2c3d4e5f6",
    "build_date", "2024-01-15",
    "java_version", System.getProperty("java.version"),
    "spring_boot_version", "2.7.8"
);

// Infrastructure information
Info infraInfo = Info.build()
    .name("infrastructure")
    .help("Infrastructure and deployment information")
    .labelNames("environment", "region")
    .register();

infraInfo.labels("production", "us-east-1").info(
    "kubernetes_version", "1.25.4",
    "node_count", "12",
    "cluster_name", "prod-cluster",
    "ingress_controller", "nginx-1.5.1"
);

// Feature flags and configuration
Info featureFlags = Info.build()
    .name("feature_flags")
    .help("Feature flag states")
    .labelNames("service")
    .register();

featureFlags.labels("user-service").info(
    "new_auth_enabled", "true",
    "rate_limiting_enabled", "false", 
    "cache_version", "v2",
    "experimental_features", "disabled"
);

// Database configuration
Info dbConfig = Info.build()
    .name("database_config")
    .help("Database configuration and settings")
    .labelNames("database_name", "role")
    .register();

dbConfig.labels("users_db", "primary").info(
    "engine", "PostgreSQL",
    "version", "14.5",
    "max_connections", "100",
    "shared_preload_libraries", "pg_stat_statements",
    "timezone", "UTC"
);

Thread Safety

All info operations are thread-safe:

// Safe concurrent access
Info concurrentInfo = Info.build()
    .name("concurrent_metadata")
    .help("Thread-safe info metric")
    .register();

// Multiple threads can safely update
concurrentInfo.info("key1", "value1"); // Thread 1
concurrentInfo.info("key2", "value2"); // Thread 2

Performance Considerations

Info metrics are lightweight and optimized for infrequent updates
Setting info overwrites all previous key-value pairs for that metric instance
Use labels sparingly to avoid high cardinality
Info metrics are typically updated once at startup or during configuration changes

Integration with Monitoring

Info metrics are particularly useful for:

Alerting Context: Providing build/version information in alert notifications
Dashboard Annotations: Showing deployment information on monitoring dashboards
Troubleshooting: Correlating issues with specific versions or configurations
Compliance: Tracking software versions and configurations for audit purposes

Install with Tessl CLI

npx tessl i tessl/maven-io-prometheus--simpleclient

docs