OS Manuals

/usr/bin/refinery

Refinery is a trace-aware tail-based sampling proxy for OpenTelemetry/Honeycomb telemetry. It receives events and spans over HTTP (Honeycomb events API and OTLP/HTTP) and OTLP/gRPC, buffers spans until a trace is complete, then applies a configurable sampling decision (deterministic, dynamic, EMA-throughput, rules-based, etc.) to the whole trace before forwarding kept traces to Honeycomb or another backend. It can run alone or as a cluster, with peers found through a static list or a shared Redis, and it…

From refinery 3.4.4-r1 (enterprise-packages), captured 2026-11-08 by running refinery --help (exit 0). permalink

Also provided by 1 other package version
Usage:
  refinery [OPTIONS]

Application Options:
  -c, --config=                             config file or URL to load; can be
                                            specified more than once (default:
                                            /etc/refinery/refinery.yaml)
                                            [$REFINERY_CONFIG]
  -r, --rules_config=                       config file or URL to load; can be
                                            specified more than once (default:
                                            /etc/refinery/rules.yaml)
                                            [$REFINERY_RULES_CONFIG]
      --http-listen-address=                HTTP listen address for incoming
                                            event traffic
                                            [$REFINERY_HTTP_LISTEN_ADDRESS]
      --peer-listen-address=                Peer listen address for
                                            communication between Refinery
                                            instances
                                            [$REFINERY_PEER_LISTEN_ADDRESS]
      --grpc-listen-address=                gRPC listen address for OTLP
                                            traffic
                                            [$REFINERY_GRPC_LISTEN_ADDRESS]
      --redis-host=                         Redis host address
                                            [$REFINERY_REDIS_HOST]
      --redis-cluster-hosts=                Redis cluster host addresses
                                            [$REFINERY_REDIS_CLUSTER_HOSTS]
      --redis-username=                     Redis username. Setting this value
                                            via a flag may expose credentials -
                                            it is recommended to use the env
                                            var or a configuration file.
                                            [$REFINERY_REDIS_USERNAME]
      --redis-password=                     Redis password. Setting this value
                                            via a flag may expose credentials -
                                            it is recommended to use the env
                                            var or a configuration file.
                                            [$REFINERY_REDIS_PASSWORD]
      --redis-auth-code=                    Redis AUTH code. Setting this value
                                            via a flag may expose credentials -
                                            it is recommended to use the env
                                            var or a configuration file.
                                            [$REFINERY_REDIS_AUTH_CODE]
      --honeycomb-api=                      Honeycomb API URL
                                            [$REFINERY_HONEYCOMB_API]
      --honeycomb-api-key=                  Honeycomb API key (for logger and
                                            metrics). Setting this value via a
                                            flag may expose credentials - it is
                                            recommended to use the env var or a
                                            configuration file.
                                            [$REFINERY_HONEYCOMB_API_KEY]
      --logger-api-key=                     Honeycomb logger API key. Setting
                                            this value via a flag may expose
                                            credentials - it is recommended to
                                            use the env var or a configuration
                                            file.
                                            [$REFINERY_HONEYCOMB_LOGGER_API_KEY]
      --logger-additional-attributes=       Additional attributes to add to all
                                            logs written by the Honeycomb
                                            logger. When supplying via a
                                            environment variable, the value
                                            should be a string of
                                            comma-separated key-value pairs.
                                            When supplying via the command
                                            line, the value should be a key
                                            value pair. If multiple key-value
                                            pairs are needed, each should be
                                            supplied via its own command line
                                            flag. The key-value pairs must use
                                            ':' as the separator.
                                            [$REFINERY_HONEYCOMB_LOGGER_ADDITIO-

                                            NAL_ATTRIBUTES]
      --opamp-server-url=                   URL of the OpAMP server to use for
                                            remote management.
                                            [$REFINERY_OPAMP_ENDPOINT]
      --telemetry-endpoint=                 Endpoint to send Refinery's
                                            internal telemetry to. This is
                                            separate from the Honeycomb API
                                            endpoint and is used for sending
                                            metrics about Refinery's
                                            performance.
                                            [$REFINERY_TELEMETRY_ENDPOINT]
      --otel-metrics-api-key=               API key for OTel metrics if being
                                            sent to Honeycomb. Setting this
                                            value via a flag may expose
                                            credentials - it is recommended to
                                            use the env var or a configuration
                                            file.
                                            [$REFINERY_OTEL_METRICS_API_KEY]
      --otel-metrics-additional-attributes= Additional attributes to add as
                                            resource attributes on all
                                            OpenTelemetry metrics emitted by
                                            Refinery. When supplying via a
                                            environment variable, the value
                                            should be a string of
                                            comma-separated key-value pairs.
                                            When supplying via the command
                                            line, the value should be a key
                                            value pair. If multiple key-value
                                            pairs are needed, each should be
                                            supplied via its own command line
                                            flag. The key-value pairs must use
                                            ':' as the separator.
                                            [$REFINERY_OTEL_METRICS_ADDITIONAL_-

                                            ATTRIBUTES]
      --otel-traces-api-key=                API key for OTel traces if being
                                            sent to Honeycomb. Setting this
                                            value via a flag may expose
                                            credentials - it is recommended to
                                            use the env var or a configuration
                                            file.
                                            [$REFINERY_OTEL_TRACES_API_KEY]
      --query-auth-token=                   Token for debug/management queries.
                                            Setting this value via a flag may
                                            expose credentials - it is
                                            recommended to use the env var or a
                                            configuration file.
                                            [$REFINERY_QUERY_AUTH_TOKEN]
      --available-memory=                   The maximum memory available for
                                            Refinery to use (ex: 4GiB).
                                            [$REFINERY_AVAILABLE_MEMORY]
      --send-key=                           The Honeycomb API key that Refinery
                                            can use to send data to Honeycomb.
                                            [$REFINERY_SEND_KEY]
  -d, --debug                               Runs debug service (on the first
                                            open port between localhost:6060
                                            and :6069 by default)
  -v, --version                             Print version number and exit
      --interface-names                     Print system's network interface
                                            names and exit.
  -V, --validate                            Validate the configuration files,
                                            writing results to stdout, and exit
                                            with 0 if valid, 1 if invalid.
      --no-validate                         Do not attempt to validate the
                                            configuration files. Makes
                                            --validate meaningless.
      --write-config=                       After applying defaults,
                                            environment variables, and command
                                            line values, write the loaded
                                            configuration to the specified file
                                            as YAML and exit.
      --write-rules=                        After applying defaults, write the
                                            loaded rules to the specified file
                                            as YAML and exit.

Help Options:
  -h, --help                                Show this help message
Options (29)
OptionDescriptionSource
-c, --configconfig file or URL to load;help
-r, --rules_configconfig file or URL to load;help
--http-listen-addressHTTP listen address for incoming event traffic [$REFINERY_HTTP_LISTEN_ADDRESS]help
--peer-listen-addressPeer listen address for communication between Refinery instances [$REFINERY_PEER_LISTEN_ADDRESS]help
--grpc-listen-addressgRPC listen address for OTLP traffic [$REFINERY_GRPC_LISTEN_ADDRESS]help
--redis-hostRedis host address [$REFINERY_REDIS_HOST]help
--redis-cluster-hostsRedis cluster host addresses [$REFINERY_REDIS_CLUSTER_HOSTS]help
--redis-usernameRedis username.help
--redis-passwordRedis password.help
--redis-auth-codeRedis AUTH code.help
--honeycomb-apiHoneycomb API URL [$REFINERY_HONEYCOMB_API]help
--honeycomb-api-keyHoneycomb API key (for logger and metrics).help
--logger-api-keyHoneycomb logger API key.help
--logger-additional-attributesAdditional attributes to add to all logs written by the Honeycomb logger.help
--opamp-server-urlURL of the OpAMP server to use for remote management.help
--telemetry-endpointEndpoint to send Refinery's internal telemetry to.help
--otel-metrics-api-keyAPI key for OTel metrics if being sent to Honeycomb.help
--otel-traces-api-keyAPI key for OTel traces if being sent to Honeycomb.help
--query-auth-tokenToken for debug/management queries.help
--available-memoryThe maximum memory available for Refinery to use (ex: 4GiB).help
--send-keyThe Honeycomb API key that Refinery can use to send data to Honeycomb.help
-d, --debugRuns debug service (on the first open port between localhost:6060 and :6069 by default)help
-v, --versionPrint version number and exithelp
--interface-namesPrint system's network interface names and exit.help
-V, --validateValidate the configuration files, writing results to stdout, and exit with 0 if valid, 1 if invalid.help
--no-validateDo not attempt to validate the configuration files.help
--write-configAfter applying defaults, environment variables, and command line values, write the loaded configuration to the specified file as YAML and exit.help
--write-rulesAfter applying defaults, write the loaded rules to the specified file as YAML and exit.help
-h, --helpShow this help messagehelp

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.