startAsyncAgent

fun startAsyncAgent(configFilename: String, exitOnMissingConfig: Boolean, logBanner: Boolean = true): EmbeddedAgentInfo(source)

Starts an Agent on a background thread and returns once it has started, suitable for embedding inside another JVM application.

Unlike startSyncAgent, this does not block for the Agent's lifetime. It waits only for startup -- the admin and metrics servers binding their ports -- and not for a proxy connection. The Agent's lifecycle is then owned by the caller via the returned EmbeddedAgentInfo, which exposes the agent's launchId and agentName and a shutdown() method for graceful shutdown.

Return

An EmbeddedAgentInfo handle for inspecting and shutting down the launched Agent.

Parameters

configFilename

Path or URL to the HOCON config file. Forwarded to the AgentOptions config-filename constructor so it follows the same resolution rules as the --config CLI flag.

exitOnMissingConfig

Pass false when embedding: a config that can't be loaded or parsed, a setting that is invalid, or -v/-u then throws io.prometheus.common.ConfigLoadException for the host to catch. true gives the standalone CLI's behavior, which requires a config and exits the process on any of these, host and all.

logBanner

When true (default), logs the Agent ASCII banner and version on startup. Pass false to suppress banner output when embedding inside an app that owns its own logging surface. Java callers can leave it out too: @JvmOverloads gives them the two-argument form, which a Kotlin default alone doesn't.

Throws

when exitOnMissingConfig is false and the config can't be loaded or parsed, or a setting is invalid, whether it comes from the config or an environment variable: a value of the wrong type or out of range, an unresolved ${…} substitution, a malformed proxy endpoint, a duplicate pathConfigs or filters entry, a filter regex that doesn't compile, or an HTTPS trust store or TLS certificate file that is missing or malformed. Credentials in a config URL are redacted from its message and from every message in its cause chain.

if the Agent fails to start, for example because its admin or metrics port is already in use. The startup failure is the cause, and whatever the Agent had opened is released first.


fun startAsyncAgent(config: Config, logBanner: Boolean = true): EmbeddedAgentInfo(source)

Starts an Agent from a config built in memory, on a background thread, and returns once it has started, as the startAsyncAgent that takes a config file does. A host that holds the agent's settings itself, such as a token, a trusted certificate (agent.tls.trustCertCollectionPem), or credentials in a scrape URL, passes them here without writing a config file that would hold them on disk.

config is the tree a config file holds, rooted at agent: build it with ConfigFactory.parseString, ConfigFactory.parseMap, or ConfigValueFactory.fromMap(...).toConfig(). It falls back to ConfigFactory.load() and is then resolved, as a config file is, so a ${?ENV_VAR} substitution in it works. The AGENT_CONFIG environment variable is not read, but the environment variables of single settings, such as AGENT_TOKEN or PROXY_HOSTNAME, still take precedence over it, as they do over a config file.

The agent is always started embedded: a config it can't use throws io.prometheus.common.ConfigLoadException, and never exits the process.

Return

An EmbeddedAgentInfo handle for inspecting and shutting down the launched Agent.

Parameters

config

The agent's configuration, rooted at agent.

logBanner

When true (default), logs the Agent ASCII banner and version on startup. Pass false to suppress banner output when embedding inside an app that owns its own logging surface.

Throws

when a setting is invalid, in the cases the startAsyncAgent that takes a config file lists.

if the Agent fails to start, for example because its admin or metrics port is already in use. The startup failure is the cause, and whatever the Agent had opened is released first.