Update the fields in config.toml
to customize your configuration.
The default configuration at installation contains the minimum configuration needed to run Refinery.
Supported sampling methods and their configuration are set in rules.toml
.
When running Refinery within Docker, be sure to mount the directory containing configuration and rules files. This is because the configuration component, Viper, monitors the directory containing the files, not the files themselves.
The default Refinery configuration uses a hardcoded peer list for file-based peer management.
It uses the DeterministicSampler
Sampling Method and a SampleRate
of 1, meaning that no traffic will be dropped.
To see the full set of default fields, see GitHub for the full configuration file.
See GitHub for an example configuration file.
Use the fields below to customize your configuration file.
ListenAddr
nginx
in front to do the decryption.
Should be in 0.0.0.0:8080
form.
HTTP endpoints support both Honeycomb JSON and OpenTelemetry OTLP binary formatted data.GRPCListenAddr
nginx
in front to do the decryption. Should be in 0.0.0.0:9090
form.
Refinery can be configured to receive OpenTelemetry OTLP traffic over gRPC with GRPCListenAddr
.
If the environment variable REFINERY_GRPC_LISTEN_ADDRESS
is set, REFINERY_GRPC_LISTEN_ADDRESS
takes precedence and this GRPCListenAddr
value is ignored.PeerListenAddr
nginx
in front to do the decryption.
Must be different from the ListenAddr
setting.
Should be in 0.0.0.0:8081
form.CompressPeerCommunication
APIKeys
HoneycombAPI
SendDelay
BatchTimeout
libhoney
[100ms]. Eligible for live reload.TraceTimeout
MaxBatchSize
500
.SendTicker
LoggingLevel
UpstreamBufferSize
and PeerBufferSize
DebugServiceAddr
-d
is specified.
The debug service runs on the first open port between localhost:6060
and localhost:6069
by default.AddHostMetadataToTrace
meta.refinery
.
(For example, meta.refinery.local_hostname
)EnvironmentCacheTTL
HoneycombAPI
config value. Default is 1 hour (1h
). Not eligible for live reload.The EnvironmentCacheTTL
configuration option is not valid for Honeycomb Classic.
AddRuleReasonToTrace
meta.refinery.reason
.
This field contains text indicating which rule was evaluated that caused the trace to be included.
Default is false
.
Eligible for live reload.AdditionalErrorFields
dataset
, apihost
, and environment
are always included. Fields not present in the span do not appear in error log. Default is [“trace.span_id”]. Eligible for live reload.AddSpanCountToRoot
meta.span_count
, to root spans, which indicates the number of child spans on the trace at the time that the sampling decision was made.
This value is available to the rules-based sampler, making it possible to write rules that are dependent upon the number of spans in the trace.
Default is false
.
Eligible for live reload.CacheOverrunStrategy
CacheOverrunStrategy
to resize
means that when a cache overrun occurs, the cache shrinks and never grows again, which is generally not helpful unless occurring because of a permanent change in traffic patterns.
Setting CacheOverrunStrategy
to impact
means that the items having the most impact on the cache size are ejected from the cache earlier than normal, but the cache is not resized.
In both cases, CacheOverrunStrategy
only applies if MaxAlloc
is nonzero.
Default is resize
for backwards compatibility but impact
is recommended for most installations.
Eligible for live reload.For proper data distribution, each Refinery process needs to know how to identify and communicate with its peers, the other Refinery processes participating in the cluster. The list of peer identifiers can be referenced dynamically through redis (redis-based peer management, recommended) or set explicitly in a hard-coded list in the config file (file-based peer management).
All of the peer management options are set within the [Peer Management]
section of the Refinery config file.
Configuring Refinery for peer management with Redis requires more configuration information than the default file-based peer management, but is recommended so that as a Refinery cluster scales up with new instances, existing instances learn of their new peers without further intervention.
Refinery needs to know the Redis hostname and port, which can be specified in one of two ways:
REFINERY_REDIS_HOST
environment variable orRedisHost
field in the config fileSimilarly, a password for Redis can be specified:
REFINERY_REDIS_PASSWORD
environment variable orRedisPassword
field in the config fileTo customize Redis-based Peer Management for your environment, the following fields can be set under the [Peer Management]
section of config.toml
:
Type
redis
to use redis for managing the peer registry.RedisHost
REFINERY_REDIS_HOST
is set, REFINERY_REDIS_HOST
takes precedence and this RedisHost
value is ignored.
Not eligible for live reload.
The redis
host should be a hostname and a port.
For example: redis.mydomain.com:6379
.
The example config file has localhost:6379
, which will not work with more than one host.RedisUsername
REFINERY_REDIS_USERNAME
is set, REFINERY_REDIS_USERNAME
takes precedence and this RedisUsername
value is ignored.
Not eligible for live reload.RedisPassword
REFINERY_REDIS_PASSWORD
is set, REFINERY_REDIS_PASSWORD
takes precedence and this RedisPassword
value is ignored.
Not eligible for live reload.UseTLS
IdentifierInterfaceName
IdentifierInterfaceName
field.
Refinery will use the first available unicast address on the given interface as its peering identifier to register in redis.
The unicast address will be IPv4 by default or IPv6 if UseIPV6Identifier
is set to true
.UseIPV6Identifier
true
if the peering network is IPv6 and IdentifierInterfaceName
is set.
Refinery will use the first IPv6 unicast address found instead of IPv4.RedisIdentifier
IdentifierInterfaceName
.File-based peer management is the default behavior. This peer management option is not recommended if you expect to increase your Refinery instances due to the intensive process required to update configuration files.
To use file-based Peer Management, configure the following fields in the [Peer Management]
section of config.toml
:
Type
file
to use the Refinery configuration file to list Refinery peers.Peers
scheme
, hostname
(or ip address
), and port
.
All servers in the cluster should be in this list, including this host.Refinery supports the following environment variables. Environment variables take precedence over file configuration.
Environment Variable | Configuration Field |
---|---|
REFINERY_GRPC_LISTEN_ADDRESS |
GRPCListenAddr |
REFINERY_REDIS_HOST |
PeerManagement.RedisHost |
REFINERY_REDIS_USERNAME |
PeerManagement.RedisUsername |
REFINERY_REDIS_PASSWORD |
PeerManagement.RedisPassword |
REFINERY_HONEYCOMB_API_KEY |
HoneycombLogger.LoggerAPIKey |
REFINERY_HONEYCOMB_METRICS_API_KEY REFINERY_HONEYCOMB_API_KEY |
HoneycombMetrics.MetricsAPIKey |
REFINERY_QUERY_AUTH_TOKEN |
QueryAuthToken |
REFINERY_HONEYCOMB_METRICS_API_KEY
takes precedence over REFINERY_HONEYCOMB_API_KEY
for the HoneycombMetrics.MetricsAPIKey
configuration.
There are a few components of Refinery with multiple implementations; the config file lets you choose your desired implementation.
For example, there are two logging implementations: one that uses logrus
and sends logs to STDOUT
, and a honeycomb
implementation that sends the log messages to a Honeycomb dataset instead.
Components with multiple implementations have one top level config item that lets you choose which implementation to use and then a section further down with additional config options for that choice. For example, the Honeycomb logger requires an API key.
Changing implementation choices requires a process restart; these changes will not be picked up by a live configuration reload. (Individual configuration options for a given implementation may be eligible for live reload).
Collector describes which collector to use for collecting traces.
The only current valid option is InMemCollector
.
More can be added by adding implementations of the Collector interface.
Use the fields below to modify your Collector settings.
CacheCapacity
CacheCapacity
value.
For guidance on how to best configure the CacheCapacity
value, please refer to the Scale and Troubleshoot documentation.
In addition, a cache remembers the sampling decision for any spans that might come in after the trace has been marked “complete” (either by timing out or seeing the root span); that capacity will be 5x this value.
This setting is eligible for live reload; growing the cache capacity with a live config reload is fine.
Avoid shrinking it with a live reload (you can, but it may cause temporary odd sampling decisions).
If the cache capacity is too low, the collect_cache_buffer_overrun
metric will increment.
If this indicator occurs, you should increase the CacheCapacity
value.MaxAlloc
Logger describes which logger to use for Refinery logs.
Valid options are logrus
and honeycomb
.
Set where log events go in this section. Use honeycomb
to send logs to the Honeycomb API. Use logrus
to send logs to STDOUT
.
LoggerHoneycombAPI
LoggerAPIKey
APIKeys
used to authenticate regular traffic.
Eligible for live reload.LoggerDataset
LoggerSamplerEnabled
LoggerSamplerThroughput
There are no configurable options for the logrus
logger yet.
Metrics describes which service to use for Refinery metrics.
Valid options are prometheus
and honeycomb
.
The prometheus
option starts a listener that will reply to a request for /metrics
.
The honeycomb
option will send summary metrics to the Honeycomb dataset you specify.
Refinery emits metrics as a Honeycomb event containing all values at each reporting interval. This configuration does not send OTLP Metrics to Honeycomb.
MetricsHoneycombAPI
MetricsAPIKey
MetricsDataset
MetricsReportingInterval
MetricsListenAddr
Here ends the list of the general Refinery configuration options. Remember to customize your Sampling Methods configuration to complete your Refinery set-up.
Did you find what you were looking for?