Advanced Agent Configuration
The Posit Chronicle agent configuration file is located at /etc/posit-chronicle-agent/posit-chronicle-agent.gcfg. This configuration is read at startup and controls the operation of the service.
Sample Configuration
Below is an example configuration file for a Chronicle server. All of the fields are included, and fields with default values have their values set to the default value. In the example below, all of the fields are commented out, because the agent will automatically self-configure for many installations, making it unnecessary to set any of these values.
/etc/posit-chronicle-agent/posit-chronicle-agent.gcfg
[Agent]
; Environment = ""
[Server]
; Address = "http://localhost:5252"
; SkipTLSVerify = true
[Connect]
; APIKey = ""
; MetricsScrapeInterval = 60s
; MetricsURL = "http://localhost:3232/metrics"
; PrometheusSkipTLSVerify = true
; ServerURL = "http://localhost:3939"
; SkipTLSVerify = true
[Workbench]
; APIKey = ""
; ConfigLocation = "/etc/rstudio/rserver.conf"
; MetricsScrapeInterval = 60s
; MetricsURL = "http://localhost:8989/metrics"
; PrometheusSkipTLSVerify = true
; ServerURL = "http://localhost:8787"
[Logging]
; FilePath = ""
; Format = "text"
; Level = "info"
[Metrics]
; Enabled = false
; Port = 8888File Format
The Posit Chronicle configuration file uses the gcfg (Go Config) format, which is derived from the Git Config format.
Environment Variables
On startup, the Chronicle agent scans the system for environment variables with the prefix CHRONICLE_. These variables are automatically associated to configuration settings based on the configuration section and the property name.
Environment variables take precedence over settings in the configuration file.
This example uses environment variables to set Server.Address, Server.SkipTLSVerify, and Logging.Level:
CHRONICLE_SERVER_ADDRESS=https://chronicle-server
CHRONICLE_SERVER_SKIPTLSVERIFY=false
CHRONICLE_LOGGING_LEVEL=debugThese environment variables are equivalent to the configuration:
[Server]
Address = "https://chronicle-server"
SkipTLSVerify = false
[Logging]
Level = "debug"Agent
The Agent section contains configuration properties which control globally applied behaviors ot the Chronicle agent.
These properties must appear after Agent in the configuration file.
Environment
The Chronicle agent will tag all metrics captured by this agent with the provided value as the environment. Use this value to organize data sent to a single Chronicle server from multiple distinct clusters.
Type: string
Default: <empty-string>
Server
The Server section contains configuration properties which control how the Chronicle agent communicates with the Chronicle server.
These properties must appear after Server in the configuration file.
Address
The network address at which the Chronicle server is listening for requests from agents.
Type: string
Default: http://localhost:5252
SkipTLSVerify
Skip verification of TLS certificates for requests sent to the Chronicle server.
Type: boolean
Default: true
Logging
The Logging section contains configuration properties which control how the Chronicle agent logs events.
These properties must appear after Logging in the configuration file.
FilePath
The optional file location (e.g., /var/log/chronicle-agent.log) where the Chronicle agent should store logs in addition to STDERR. The specified folder must exist. The agent always writes logs to STDERR, and if this value is unset, the agent will only be write logs there.
Type: string
Default: <empty-string>
Format
Choose the log output format type, between text and json. This value is not case sensitive.
Type: string
Default: text
Level
Choose the log output level. The options for this value are DEBUG, INFO, WARN, and ERROR. This value is not case sensitive.
Type: string
Default: info
Metrics
The Metrics section contains configuration properties which control whether the agent emits metrics about itself and where those metrics are served.
These properties must appear after Metrics in the configuration file.
Enabled
Enable the Chronicle agent to expose Prometheus metrics about itself.
Type: boolean
Default: false
Port
If enabled, the port at which Prometheus should serve the /metrics endpoint.
Type: string
Default: 8888
Connect
The Connect section contains configuration properties which control how the Chronicle agent interacts with Posit Connect.
These properties must appear after Connect in the configuration file.
APIKey
The API key which the Chronicle agent should use to interact with Connect. The API key must be associated with an “Administrator” user. This value is required if running the Chronicle agent with Connect.
Type: string
Default: <empty-string>
MetricsScrapeInterval
The frequency with which the Chronicle agent should send requests to Connect’s API and Prometheus metrics endpoints.
Type: duration
Default: 60s
MetricsURL
The URL at which Connect is serving its Prometheus metrics.
Type: string
Default: http://localhost:3232/metrics
PrometheusSkipTLSVerify
Skip verification of TLS certificates for requests sent to the Prometheus metrics endpoint exposed by Connect.
Type: boolean
Default: true
ServerURL
The URL at which Connect is serving its API.
Type: string
Default: http://localhost:3939
SkipTLSVerify
Skip verification of TLS certificates for requests sent to the Connect API.
Type: boolean
Default: true
Workbench
The Workbench section contains configuration properties which control how the Chronicle agent interacts with Posit Workbench.
These properties must appear after Workbench in the configuration file.
APIKey
The API key which the Chronicle agent should use to interact with Workbench. The API key should be an admin, read only key. This value is optional if running the Chronicle agent with Workbench, but named user data is only available with this value set.
Type: string
Default: <empty-string>
ConfigLocation
The file path to the Workbench configuration file, if Workbench is not using the default path.
Type: string
Default: "/etc/rstudio/rserver.conf"
MetricsScrapeInterval
The frequency with which the Chronicle agent should send requests to Workbench’s API and Prometheus metrics endpoints.
Type: duration
Default: 60s
MetricsURL
The URL at which Workbench is serving its Prometheus metrics.
Type: string
Default: http://localhost:8989/metrics
PrometheusSkipTLSVerify
Skip verification of TLS certificates for requests sent to the Prometheus metrics endpoint exposed by Workbench.
Type: boolean
Default: true
ServerURL
The URL at which Workbench is serving its API.
Type: string
Default: http://localhost:8787