Appendix: Advanced Server Configuration
The Posit Chronicle server configuration file is located at /etc/posit-chronicle/posit-chronicle.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.
/etc/posit-chronicle/posit-chronicle.gcfg
; Posit Chronicle configuration file
; See the configuration guide for details on the configuration file format.
; [ExampleSection]
; BooleanProperty = true
; StringProperty1 = "hello"
; StringProperty2 = "escape \"quotes\" within a value"
; DurationProperty = 300s
[HTTP]
;; Chronicle will listen on this network address for HTTP connections. One of
;; HTTP.Listen or HTTPS.Listen is required for Chronicle to function.
Listen = :5252
[HTTPS]
;; Listen for HTTPS connections, which requires TLS certificate and key files.
; Listen = :443
; Key = ""
; Certificate = ""
[LocalStorage]
Enabled = true
; Location = ./chronicle-data or /var/lib/posit-chronicle/data under systemd
; RetentionPeriod accepts a duration string input. 0 implies infinite retention, disabling file expiration.
; For example:
; 1s for 1 second, 5m for 5 minutes, 12h for 12 hours, 7d for one week, 365d for one year, 0 for unbound retention.
; Units shorter than seconds or longer than days, such as milliseconds and weeks, are not supported.
RetentionPeriod = 30d
[S3Storage]
Enabled = false
; Bucket = ""
; Prefix = ""
; Profile = "" ;; uses the $AWS_PROFILE environment variable by default
; Region = "" ;; uses the $AWS_REGION environment variable by default
[Logging]
ServiceLog = STDOUT
ServiceLogLevel = INFO
ServiceLogFormat = TEXT ;; one of TEXT or JSON
[Metrics]
;; Enable Prometheus metrics for the server itself.
Enabled = trueFile 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 server 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 HTTP.Listen and Logging.ServiceLogLevel:
CHRONICLE_HTTP_LISTEN=:80
CHRONICLE_LOGGING_SERVICELOGLEVEL=debugThese environment variables are equivalent to the configuration:
[HTTP]
Listen = ":80"
[Logging]
ServiceLogLevel = DEBUGHTTP
The HTTP section contains configuration properties which control the ability of Posit Chronicle to listen for HTTP requests.
These properties must appear after [HTTP] in the configuration file.
Listen
Posit Chronicle will listen on this network address for HTTP connections. The network address can be of the form :80 or 192.168.0.1:80. This must correspond with the value set for the CHRONICLE_SERVER_ADDRESS environment variable set for the Chronicle agent.
Type: string
Default: :5252
HTTPS
The HTTPS section contains configuration properties which control the ability of Posit Chronicle to listen for HTTPS requests.
These properties must appear after [HTTPS] in the configuration file.
Listen
Posit Chronicle will listen on this network address for HTTPS connections. The network address can be of the form :80 or 192.168.0.1:80. This must correspond with the value set for the CHRONICLE_SERVER_ADDRESS environment variable set for the Chronicle agent.
Type: string
Default: <empty-string>
Certificate
Path to a PEM encoded TLS certificate file. If the certificate is signed by a certificate authority, the certificate file should be the concatenation of the server’s certificate followed by the CA’s certificate. Must be paired with an HTTPS.Key.
Type: string
Default: <empty-string>
Key
Path to a PEM encoded private key file corresponding to the certificate specified with HTTPS.Certificate.
Type: string
Default: <empty-string>
LocalStorage
The LocalStorage section contains configuration properties which control options used when allowing the Posit Chronicle server to write data to a locally accessible filesystem.
These properties must appear after [LocalStorage] in the configuration file.
Enabled
When set to true, Posit Chronicle will write data to the local filesystem.
Type: boolean
Default: true
Location
Override the default location for data storage on the local filesystem. This property can be a relative or absolute path.
Type: string
Default: /var/lib/posit-chronicle/data
RetentionPeriod
Set a duration after which the Chronicle server will delete created files. Once per day, the Chronicle server will check the folders where parquet files are written for folders older than the retention period and delete any folders found.
Type: duration
Default: 30d
S3Storage
The S3Storage section contains configuration properties which control options used when allowing the Posit Chronicle server to write 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 Posit 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, Posit Chronicle will create 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. Posit Chronicle will first search for AWS environment variables; if none are set it will attempt 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.
Type: string
Default: <empty-string>
Logging
The Logging section contains configuration properties which control logging of messages from the Chronicle server itself.
These properties must appear after [Logging] in the configuration file.
ServiceLog
Set the output to which log messages will be written. This value can be STDOUT, STDERR, or a path to a directory on the local disk. If set to a directory path, log messages will appear in a file called chronicle.log. This path can be absolute (/absolute/path/to/folder) or relative (./relative/folder).
Type: string
Default: STDOUT
ServiceLogevel
Choose the log output level. The options for this value are TRACE, DEBUG, INFO, WARN, and ERROR. This value is not case sensitive.
Type: string
Default: INFO
ServiceLogFormat
Choose the log output format type, between text and json. This value is not case sensitive.
Type: string
Default: TEXT
Metrics
The Metrics section contains configuration properties which control options used to emit metrics related to the Posit Chronicle server.
These properties must appear after [Metrics] in the configuration file.
Enabled
If this value is set to true, the Posit Chronicle server will expose a Prometheus metrics endpoint listen address specified by the Listen field of either the HTTP or HTTPS section.
Type: boolean
Default: true
Profiling
Enabled
If this value is set to true, the Posit Chronicle server will expose a pprof profiling server at the listen address specified by the Listen field. This pprof profiling data is primarily useful for debugging internal Chronicle server issues.
Type: boolean
Default: false
Listen
Posit Chronicle will listen on this network address for profiling requests. The network address can be of the form :80 or 192.168.0.1:80.
Type: string
Default: :3030