start Async Agent
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
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.
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.
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.
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
The agent's configuration, rooted at agent.
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.