Advanced Chronicle Configuration
In general, Posit Workbench or Posit Connect control the configuration of Chronicle. In some rare cases, however, you might want to override the default settings and configure Chronicle directly. This section describes how to provide custom configuration settings for Chronicle.
Local configuration file
You can provide custom configuration settings for Chronicle by creating a local configuration file named chronicle-local.gcfg on the machine where Chronicle is running. This file must be located in the same directory where the main Chronicle configuration file is located.
- For Workbench, the main Chronicle configuration file is located at
/var/lib/rstudio-server. - For Connect, the main Chronicle configuration file is located at
/etc/rstudio-connect/chronicle.
Chronicle reads this local configuration file on startup, and any settings provided in this file take precedence over settings provided by Connect or Workbench.
Be cautious when providing custom configuration settings for Chronicle, as incorrect settings may result in operational problems, including Chronicle failing to start or function properly.
Sample configuration
Below is an example configuration file for Chronicle. All of the fields are included, but set values only for the fields you need to override.
/etc/rstudio-connect/chronicle/chronicle-local.gcfg
; Posit Chronicle configuration file
[Agent]
; Environment = ""
[Logging]
; Output = STDOUT
; Level = INFO
; Format = JSON
[LocalStorage]
; Enabled = true
; Location = /var/lib/posit-chronicle/data
; Access = group
[S3Storage]
; Enabled = false
; Bucket = ""
; Prefix = ""
; Profile = ""
; Region = ""
[Connect]
; APIKey = ""
; APIScrapeInterval = 20m
; MetricsScrapeInterval = 60s
; MetricsURL = "http://localhost:3232/metrics"
; PrometheusSkipTLSVerify = true
; ServerURL = "http://localhost:3939"
; SkipTLSVerify = true
; LogOTLPEndpoint = ""
[Workbench]
; APIKey = ""
; APIScrapeInterval = 20m
; MetricsScrapeInterval = 60s
; MetricsURL = "http://localhost:8989/metrics"
; PrometheusSkipTLSVerify = true
; ServerURL = "http://localhost:8787"
; SkipTLSVerify = true
; LogOTLPEndpoint = ""File format
The Posit Chronicle configuration file uses the gcfg (Go Config) format, which is derived from the Git Config format.
Agent
The Agent section contains configuration properties which control behaviors related to gathering data from Connect or Workbench.
These properties must appear after [Agent] in the configuration file.
Environment
Chronicle tags all metrics captured by this process with the provided value as the environment. Use this value to organize data from multiple distinct clusters. This is most commonly used to differentiate between production and staging environments, but you can set this value to anything that suits your needs for organizing your Chronicle data.
Type: string
Default: <empty-string>
Logging
The Logging section contains configuration properties which control logging of messages from Chronicle itself.
These properties must appear after [Logging] in the configuration file.
Output
The optional file location (e.g., /var/log/chronicle-agent.log) where Chronicle should store log messages. In addition to a file location, you may also specify STDOUT or STDERR to have Chronicle write logs to standard output or standard error, respectively.
Type: string
Default: <empty-string>
Format
Choose the log output format type, between console and json. This value is not case sensitive.
Type: string
Default: console
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
LocalStorage
The LocalStorage section contains configuration properties which control options used when Chronicle writes data to a locally accessible filesystem.
These properties must appear after [LocalStorage] in the configuration file.
Enabled
When set to true, Chronicle writes data to the local filesystem.
Type: boolean
Default: true
Location
Override the default location for data storage on the local filesystem. This property should be an absolute path.
Type: string
Default: /var/lib/posit-chronicle/data
Access
Sets the permissions for data files and directories created by Chronicle on the local filesystem. This value can be all, group, or owner.
- If set to
all, data files will have permissions of 0664 and data directories will have permissions of 0775, allowing any user to read data files and traverse data directories. - If set to
group, data files will have permissions of 0660 and data directories will have permissions of 0770, allowing the owner and group to read data files and traverse data directories. - If set to
owner, data files will have permissions of 0600 and data directories will have permissions of 0700, allowing only the owner to read data files and traverse data directories.
Type: string
Default: group
S3Storage
The S3Storage section contains configuration properties which control options used when Chronicle writes data to an AWS S3 object store.
These properties must appear after [S3Storage] in the configuration file.
Enabled
Set this value to true to enable Chronicle to write data to the S3 object store.
Type: boolean
Default: false
Bucket
The S3 bucket to use for data storage. This value is required if Enabled is set to true.
Type: string
Default: <empty-string>
Prefix
An optional prefix to use when writing to the S3 bucket. If omitted, Chronicle creates directories directly under the bucket root.
Type: string
Default: <empty-string>
Profile
The name of the AWS Profile to use when searching the credentials chain for AWS access. Chronicle first searches for AWS environment variables. If none are set, it attempts to load credentials from the shared config and credentials files using this profile.
Type: string
Default: <empty-string>
Region
The AWS region containing the S3 bucket to use for data storage. This value is required if Enabled is set to true.
Type: string
Default: <empty-string>
Connect
The Connect section contains configuration properties which control how Chronicle interacts with Posit Connect.
These properties must appear after [Connect] in the configuration file.
APIKey
The API key which Chronicle uses to interact with the Connect API. The API key must be associated with an “Administrator” user and provisioned with the “Administrator” role.
Type: string
Default: <empty-string>
APIScrapeInterval
The frequency with which Chronicle sends requests to Connect API endpoints for collecting metrics. This value can be no less than 10 seconds and no greater than 4 hours. This interval represents the minimum amount of time that will elapse between the start of one API scrape and the start of the next. If the API scrape takes longer than the value set here for interval, the next API scrape will not begin until the earlier scrape has finished. This interval can be adjusted to balance the granularity of data collected from Connect with CPU and database performance of the Connect instance: lowering this interval will result in increases in both data granularity and CPU/database usage.
Type: duration
Default: 20m
MetricsScrapeInterval
The frequency with which Chronicle sends requests to Connect Prometheus metrics endpoint. This value can be no less than 10 seconds and no greater than 4 hours.
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
LogOTLPEndpoint
The network address at which Chronicle should listen for OTLP HTTP requests from Posit Connect. Setting this value enables log collection.
Type: string
Default: <empty-string>
Workbench
The Workbench section contains configuration properties which control how Chronicle interacts with Posit Workbench.
These properties must appear after [Workbench] in the configuration file.
APIKey
The API key which Chronicle uses to interact with Workbench. The API key must be an administrator, 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>
APIScrapeInterval
The frequency with which Chronicle sends requests to Workbench API endpoints for collecting metrics. This value can be no less than 10 seconds and no greater than 4 hours. This interval represents the minimum amount of time that will elapse between the start of one API scrape and the start of the next. If the API scrape takes longer than the value set here for interval, the next API scrape will not begin until the earlier scrape has finished. This interval can be adjusted to balance the granularity of data collected from Workbench with CPU and database performance of the Workbench instance: lowering this interval will result in increases in both data granularity and CPU/database usage.
Type: duration
Default: 20m
MetricsScrapeInterval
The frequency with which Chronicle sends requests to Workbench Prometheus metrics endpoint. This value can be no less than 10 seconds and no greater than 4 hours.
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
SkipTLSVerify
Skip verification of TLS certificates for requests sent to the Workbench API.
Type: boolean
Default: true