Embedded Agent

If your application runs on the JVM, you can embed the prometheus-agent directly in your app instead of running a separate agent process.

When to Use

• Your application already runs on the JVM (Java, Kotlin, Scala, etc.)
• You want to avoid managing a separate agent process
• You need tight integration between your app and the agent lifecycle

Adding the Dependency

// build.gradle.kts
repositories {
  mavenCentral()
}

dependencies {
  implementation("com.pambrose:prometheus-proxy:3.1.0")
}

<!-- pom.xml -->
<dependencies>
  <dependency>
    <groupId>com.pambrose</groupId>
    <artifactId>prometheus-proxy</artifactId>
    <version>3.1.0</version>
  </dependency>
</dependencies>

Usage

import io.prometheus.Agent;
import io.prometheus.agent.EmbeddedAgentInfo;

public class EmbeddedAgentJavaExample {
  public static void main(String[] args) {
    // Start the agent in the background
    EmbeddedAgentInfo agentInfo =
      Agent.startAsyncAgent("agent-config.conf", true, true);

    System.out.println("Agent started: " + agentInfo.getAgentName());

    // Your application code runs here...
    // The agent runs in background threads

    // Stop the agent when your application exits
    agentInfo.shutdown();
  }
}

import io.prometheus.Agent

fun main() {
  // Start the agent in the background
  val agentInfo = Agent.startAsyncAgent(
    configFilename = "agent-config.conf",
    exitOnMissingConfig = true,
  )

  println("Agent started: ${agentInfo.agentName}")

  // Your application code runs here...
  // The agent runs in background coroutines

  // Stop the agent when your application exits
  agentInfo.shutdown()
}

Agent Configuration

The embedded agent uses the same HOCON configuration as the standalone agent:

// Minimal config for an embedded agent:
agent {
  proxy.hostname = "proxy-host.example.com"

  pathConfigs: [
    {
      name: "My App metrics"
      path: my_app_metrics
      url: "http://localhost:9100/metrics"
    }
  ]
}

API Reference

Agent.startAsyncAgent()

Starts the agent in background threads/coroutines.

Returns: EmbeddedAgentInfo

EmbeddedAgentInfo

How It Works

When you call startAsyncAgent():

1. The agent reads the configuration file
2. Starts background coroutines for gRPC communication
3. Connects to the proxy and registers paths
4. Returns immediately with agent metadata
5. The agent continues running in the background, processing scrape requests

Your application code runs normally while the agent handles metrics scraping in the background.