example.full.yaml

#
# Trickster 2.x Example Configuration File - Exhaustive
#
# To use this, run: trickster -config /path/to/example.full.yaml
#
# This file contains descriptions and examples for all
# Trickster configuration options. More documentation is
# available at https://github.com/trickstercache/trickster/docs/
#
# Optional configs are commented out, required configs are uncommented
# and set to common values that let you try it out with Prometheus
#
# Copyright 2018 The Trickster Authors
#

# main:
#   # instance_id allows you to run multiple Trickster processes on the same host and log to separate files
#   # Useful for baremetal, not so much for elastic deployments, so only uncomment if you really need it
#   # default is 0, which means ignored
#   instance_id: 0

#   # server_name provides the name of this server instance, used to self-identfy in Via and other Forwarding headers
#   # server_name defaults to os.Hostname() when left blank
#   server_name: ''

#   # config_include_directory overrides the default conf.d directory next to this file.
#   # Relative paths are resolved from the directory containing the primary config file.
#   # This option is valid only in the primary file, not in included files or directory mode.
#   config_include_directory: ''

# Configuration options for inbound listeners.
# The legacy frontend section and listener ports under metrics and mgmt remain
# supported for compatibility, but are deprecated. A matching listeners entry
# takes precedence over those legacy values.
#   # The default, metrics, and mgmt entries are built-in and can be customized here.
# listeners:
#   # default is built-in and the default frontend for all defined backends
#   default:
#     # protocol defines the protocol used by the listener, and defaults to http
#     protocol: http
#     # port is the port the listener uses. default uses 8480 by default
#     port: 8480
#     # address is empty by default, meaning listen on all interfaces.
#     address: ''
#     # tls_port value of 0 means disabled. A value > 0 starts only when a
#     # mapped backend provides a certificate and key. default uses 8483 by default
#     tls_port: 8483
#     # tls_address is empty by default, meaning listen on all interfaces.
#     tls_address: ''
#     # tls_watch_interval is the backstop poll for out-of-band cert/key
#     # rotation (e.g. certbot). FS events accelerate detection where supported.
#     # Changes are hot-swapped without restart. default 30s; 0 disables
#     tls_watch_interval: 30s
#     # tls_runtime_certs serves tls_port even when no mapped backend provides a
#     # certificate file; certificates are then supplied to the running process
#     # (e.g. by the Kubernetes controller from Secrets). default false
#     tls_runtime_certs: false
#     # connections_limit defines the maximum number of concurrent connections
#     # the listener may handle at any time. 0 means unlimited
#     connections_limit: 0
#
#     # read_header_timeout defines the amount of time allowed to read request headers.
#     read_header_timeout: 10s
#
#     # read_timeout bounds the time allowed to read a whole request, body included.
#     # 0 sets no bound. Default: 0
#     read_timeout: 0s
#
#     # idle_timeout closes a keep-alive connection that waits this long for its next
#     # request. 0 keeps idle connections open indefinitely. Default: 2m
#     idle_timeout: 2m
#
#     # max_header_bytes caps the bytes read for a request's line and headers.
#     # 0 selects the net/http default of 1 MB. Default: 0
#     max_header_bytes: 0
#
#     # trusted_proxies lists the addresses and CIDRs of proxies in front of this
#     # listener. A connection from one of them is attributed to the client named
#     # by its Forwarded, X-Forwarded-For or X-Real-IP header; any other connection
#     # is attributed to its peer, whatever headers it carries. See docs/configuring.md
#     trusted_proxies: [ 10.0.0.0/8 ]
#
#     # proxy_protocol accepts a PROXY protocol v1/v2 header ahead of each connection,
#     # honored from every peer when trusted_proxies is empty and only from a trusted
#     # proxy otherwise. Default: false
#     proxy_protocol: false
#
#     # ip_acl_name applies a named ip_acls entry to every connection on this
#     # listener, including mgmt and metrics. none is not valid here.
#     # See docs/ip-acl.md
#     ip_acl_name: office
#
#     # path_normalization cleans each request path before routing it, and the
#     # cleaned path is what the origin receives. See docs/configuring.md
#     path_normalization:
#       # dot_segments removes '.' and '..' segments per RFC 3986 (normalize),
#       # refuses them with 400 (reject), or leaves them (off). Default: normalize
#       dot_segments: normalize
#       # merge_slashes collapses each run of slashes to one. Default: false
#       merge_slashes: false
#       # escaped_slashes forwards %2F as data within a segment (keep), refuses
#       # it with 400 (reject), or decodes it to a separator (unescape). Default: keep
#       escaped_slashes: keep
#
#     # max_request_body_size_bytes indicates the maximum allowed request body size.
#     # Use 0 for no body allowed, and < 0 for no maximum. Default: 10MB.
#     max_request_body_size_bytes: 10485760
#
#     # truncate_request_body_too_large truncates oversized bodies instead of returning 413.
#     # Default: false.
#     truncate_request_body_too_large: false
#
#     # http3 serves this listener's routes over HTTP/3 (QUIC) in addition to
#     # HTTP/1.1 and HTTP/2. Requires a working TLS endpoint, since QUIC has no
#     # cleartext mode. Responses on the TLS/TCP endpoint advertise the HTTP/3
#     # endpoint via Alt-Svc so clients upgrade on their own. See docs/http3.md
#     http3:
#       # enabled turns on the HTTP/3 endpoint. Default: false
#       enabled: false
#       # port is the UDP port to bind. Defaults to this listener's tls_port
#       port: 8483
#       # address is the IP for the UDP socket. Defaults to tls_address
#       address: ''
#       # advertised_port is the port published in Alt-Svc. Defaults to port.
#       # Set it when a load balancer or NAT presents a different port to
#       # clients than the one bound here
#       advertised_port: 0
#
#   # metrics:
#   # 8481 is the default port for metrics
#     # port: 8481
#     # address: ''
#   # mgmt:
#   # 8484 is the default management port
#     # port: 8484
#     # address: ''
#
#   # A listener with protocol mysql accepts MySQL wire-protocol connections
#   # and requires exactly one backend with provider mysql mapped to it via
#   # the backend's listener_names. TLS ports are not supported on mysql
#   # listeners (MySQL negotiates TLS in-band on the same port).
#   mysql1:
#     protocol: mysql
#     port: 8486
#     # address: ''
#     # connections_limit: 0
#     # mysql:
#       # The complete authentication exchange must finish within this timeout.
#       handshake_timeout: 10s
#       # read_timeout bounds an in-progress command read.
#       read_timeout: 30s
#       write_timeout: 30s
#       # idle_timeout independently bounds waiting for the next command.
#       idle_timeout: 5m
#       # MySQL packet framing is currently fixed at the protocol ceiling.
#       max_packet_size_bytes: 16777215
#       max_query_size_bytes: 1048576
#     # MySQL-specific options have no direct TRK_* environment mapping and a
#     # structured origin_url does not expand ${VARIABLE}. Authenticator users
#     # do support environment expansion. Relevant reloads restart and drain
#     # this listener rather than moving established sessions. On Kubernetes,
#     # keep a MySQL listener's origin and client credentials in a Secret
#     # rather than a shared ConfigMap.
#
#   # A listener with protocol postgres accepts PostgreSQL wire-protocol
#   # connections and requires exactly one mapped backend: one with provider
#   # postgres or timescaledb, or a User Router ALB over such backends (see
#   # examples/conf/postgres-user-router.yaml). TLS is negotiated in-band on
#   # the same port, so TLS ports are not supported.
#   postgres1:
#     protocol: postgres
#     port: 5432
#     # address: ''
#     # connections_limit: 0
#     # postgres:
#       # The startup and authentication exchange must finish within this timeout.
#       handshake_timeout: 10s
#       read_timeout: 30s
#       write_timeout: 30s
#       # idle_timeout bounds the wait for a client's next message.
#       idle_timeout: 5m
#       # statements larger than this are relayed without being analyzed or cached
#       max_query_size_bytes: 1048576
#       # With an authenticator, clients authenticate with SCRAM-SHA-256. A user
#       # stored as a PostgreSQL md5 hash can only log in when allow_md5 is set,
#       # and a plaintext exchange over a non-TLS connection only with
#       # allow_cleartext_without_tls. Both default to false.
#       allow_md5: false
#       allow_cleartext_without_tls: false
#
#   # A listener with protocol moq accepts MoQ Transport sessions over native
#   # QUIC on its UDP port; TLS is part of the QUIC handshake, so TLS ports are
#   # not supported, and a backend it serves must provide a certificate in its
#   # tls block. Several moq backends may share one listener: a session is
#   # routed by the AUTHORITY and PATH of its SETUP against each backend's hosts
#   # and paths. A moq listener may share its UDP port with an HTTP/3 endpoint,
#   # or another moq listener, as long as their drafts differ.
#   moq1:
#     protocol: moq
#     port: 443
#     # address: ''
#     # moq:
#       # the client's SETUP must arrive within this timeout
#       handshake_timeout: 5s
#       # the QUIC idle timeout of the listener's connections
#       idle_timeout: 2m
#       max_sessions: 10000
#       max_requests_per_session: 1024
#       # advertised to clients in SETUP
#       max_filter_ranges: 16
#       max_request_updates: 64
#       # accepted MoQ Transport drafts, most preferred first
#       drafts: [22, 21, 20]
#       # the MOQT_IMPLEMENTATION setup option; defaults to trickster
#       implementation: ''
#       # when the listener stops, each session gets a GOAWAY naming this moqt
#       # URI to continue at, and a new request is redirected there; empty has
#       # clients reconnect where they were. Changing it restarts nothing.
#       goaway_uri: ''
#
#   # A ClickHouse listener accepts the Native binary protocol and maps to one
#   # ClickHouse backend through that backend's listener_names option.
#   clickhouse-native:
#     protocol: clickhouse
#     port: 8487
#     # address: ''
#     # connections_limit: 0
#
#   # A flight-sql listener accepts Apache Arrow Flight SQL (gRPC) connections
#   # and maps to one InfluxDB backend through that backend's listener_names
#   # option. See /docs/influxdb.md for full details. InfluxDB 3.x only.
#   influx3-flight:
#     protocol: flight-sql
#     port: 8485
#     # address: ''
#     # connections_limit: 0
#
#   # A listener with protocol tcp relays each connection's bytes, unread, to
#   # its one mapped backend: a reverseproxy (rp) backend whose origin_url
#   # supplies the host and port to dial, or an alb backend (mechanism rr)
#   # whose pool members are such backends, each connection committed to one
#   # member by weighted round robin. See docs/configuring.md#stream-listeners
#   postgres:
#     protocol: tcp
#     port: 5432
#     # address: ''
#     # connections_limit bounds the connections relayed at once; for a udp
#     # listener it bounds the sessions held at once, 1024 when unset
#     # connections_limit: 0
#     # stream tunes the relay for the tcp, tls and udp protocols
#     stream:
#       # connect_timeout bounds the lookup and dial of the backend and, on a
#       # tls listener, the wait for the client's ClientHello. Default: 10s
#       connect_timeout: 10s
#       # idle_timeout closes a connection over which no byte has moved in
#       # either direction for this long, or ends a udp session that carried
#       # no datagram for this long. Default: none for tcp and tls, 60s for udp
#       idle_timeout: 0s
#
#   # A listener with protocol tls relays TLS connections unterminated: the
#   # server name the client offers selects the mapped backend whose hosts
#   # name it, or the one mapped backend with no hosts, and the backend
#   # terminates TLS itself. tls_port and tls_runtime_certs do not apply.
#   sni:
#     protocol: tls
#     port: 8443
#
#   # A listener with protocol udp relays each client's datagrams to its one
#   # mapped backend over a session of its own, ended once idle. A udp listener
#   # binds its own port space, so it may share a port number with a tcp one.
#   dns:
#     protocol: udp
#     port: 5353

# caches:
#   default:
#     # provider defines what kind of cache Trickster uses
#     # options are bbolt, badger, filesystem, memory, redis and valkey
#     # The default is memory.
#     provider: memory

#     ## Configuration options for the Cache Index
#     # The Cache Index handles key management and retention for bbolt, filesystem and memory
#     # Redis, Valkey and BadgerDB handle those functions natively and do not use the Tricksters Cache Index
#     index:
#       # reap_interval defines how long the Cache Index reaper sleeps between reap cycles. Default is 3 (3s)
#       reap_interval: 3s
#       # flush_interval sets how often the Cache Index saves its metadata to the cache from application memory. Default is 5 (5s)
#       flush_interval: 5s
#       # index_expiry defines how long a Trickster instance will retain its cache index on startup. Default is 1 year (365 days * 24 hours = 8760 hours)
#       index_expiry: 8760h
#       # max_size_bytes indicates how large the cache can grow in bytes before the Index evicts least-recently-accessed items. default is 512MB
#       max_size_bytes: 536870912
#       # max_size_backoff_bytes indicates how far below max_size_bytes the cache size must be to complete a byte-size-based eviction exercise. default is 16MB
#       max_size_backoff_bytes: 16777216
#       # max_size_objects indicates how large the cache can grow in objects before the Index evicts least-recently-accessed items. default is 0 (infinite)
#       max_size_objects: 0
#       # max_size_backoff_objects indicates how far under max_size_objects the cache size must be to complete object-size-based eviction exercise. default is 100
#       max_size_backoff_objects: 100
#       # scan_interval defines how long the Cache Index waits between sweeps of the cache, in which it lists objects it
#       # did not know of and drops those the cache no longer holds. 0 disables the periodic sweep. default is 24h
#       scan_interval: 24h
#       # scan_batch_size is how many objects a sweep of the cache reads before it pauses. default is 512
#       scan_batch_size: 512
#       # scan_batch_pause is how long a sweep of the cache pauses after each batch of objects. default is 50ms
#       scan_batch_pause: 50ms

#     ## Configuration options when using a Memory Cache #######
#     memory:
#       # max_size_bytes is the maximum total byte cost will admit to the cache.
#       # unlike index.max_size_bytes (a soft eviction threshold), this is enforced at
#       # admission time. default is 512MB
#       max_size_bytes: 536870912
#       # num_counters is the number of keys to track for admission and eviction decisions. This is not a hard limit but a max sampling size.
#       # Recommended to use ~10x the number of unique keys you expect to hold for full utilization.
#       # default is 500000
#       num_counters: 500000

#     ## Configuration options when using a Redis Cache (provider: redis)
#     ## The redis provider serves Redis and compatible servers, Valkey included, with a pooled
#     ## connection per command. A valkey cache takes these same options under 'valkey' instead.
#     redis:
#       # client_type indicates which kind of Redis client to use. Options are: standard, cluster and sentinel
#       # default is standard
#       client_type: standard

#       ## Supported by Redis (standard) #####################################
#       ## These configurations are ignored by Redis Sentinel and Redis Cluster
#       ##
#       # endpoint defines the fqdn+port or path to a unix socket file for connecting to redis
#       # default is redis:6379
#       endpoint: redis:6379

#       ## Supported by Redis Cluster and Redis Sentinel #####################
#       ## These configurations are ignored by Redis (standard)
#       ##
#       # endpoints is used for Redis Cluster and Redis Sentinel to define a list of endpoints
#       # default is [redis:6379]
#       endpoints:
#       - redis:6379

#       ## Supported by Redis Sentinel #######################################
#       ## These configurations are ignored by Redis (standard) and Redis Cluster
#       ##
#       # sentinel_master should be set when using Redis Sentinel to indicate the Master Node
#       sentinel_master: ''

#       ## Supported by all Redis Client Types ###############################
#       ## See docs/caches.md for how these settings apply to the client

#       # protocol defines the protocol for connecting to redis (unix or tcp). tcp is default
#       protocol: tcp

#       # username provides the redis username. default is empty string ''
#       username: ''
#       # password provides the redis password. default is empty string ''
#       password: ''
#       # db is the Database to be selected after connecting to the server. default is 0
#       db: 0
#       # max_retries is the maximum number of times a read is retried after a network error. default is 3,
#       # and -1 disables retries. writes are not retried
#       max_retries: 0
#       # min_retry_backoff is the minimum backoff time between each retry
#       min_retry_backoff: 8ms
#       # max_retry_backoff is the maximum backoff time between each retry
#       max_retry_backoff: 512ms
#       # dial_timeout is the timeout for establishing new connections
#       dial_timeout: 5s
#       # read_timeout and write_timeout bound a command's wait on its connection; the longer of the two applies.
#       # default is 3s. If reached, commands will fail with a timeout instead of blocking.
#       read_timeout: 3s
#       write_timeout: 3s
#       # pool_size is the maximum number of socket connections to each server. default is 10 per CPU
#       pool_size: 20
#       # min_idle_conns is the minimum number of idle connections which is useful when establishing new connection is slow.
#       min_idle_conns: 0
#       # max_conn_age is the connection age at which client retires (closes) the connection.
#       max_conn_age: 0ms
#       # pool_timeout has no effect: a command waits for a pooled connection until one frees, within the
#       # connection's timeouts. It is accepted so that existing configurations still load
#       pool_timeout: 4000ms
#       # idle_timeout is the amount of time after which client closes idle connections.
#       idle_timeout: 5m
#       # use_tls indicates if the Redis server uses TLS encryption. default is false
#       use_tls: false

#     ## Configuration options when using a Valkey Cache (provider: valkey) ##
#     ## A valkey cache takes every option of the redis section above, with the defaults it lists except
#     ## endpoint and endpoints, which default to valkey:6379, plus these Valkey-only settings.
#     ## A redis cache can't have a valkey section, nor a valkey cache a redis section.
#     valkey:
#       client_type: standard
#       endpoint: valkey:6379
#       # in cluster mode, db selects a numbered database, which Valkey 9 serves when its
#       # cluster-databases is above the db. default is 0
#       db: 0
#       # auto_pipelining shares connections among concurrent commands. when false, each command takes a
#       # pooled connection of its own, as with the redis provider. it suits caches of small objects only,
#       # since a small read pipelined behind a multi-megabyte reply waits for it. default is false
#       auto_pipelining: false
#       # pipeline_multiplex is the log2 of the pipelined connections to each node, from 0 (one connection)
#       # to 8. when unset, the client uses up to 4 for a single server and 1 for each cluster node
#       pipeline_multiplex: 2
#       # max_flush_delay pauses the pipeline's write loop up to this long, to send more commands per
#       # write. default is 0
#       max_flush_delay: 0s
#       # read_buffer_bytes and write_buffer_bytes size each connection's buffers. default is 524288
#       read_buffer_bytes: 524288
#       write_buffer_bytes: 524288
#       replica_reads:
#         # mode is where cache reads go: none (the primary), prefer_replica, az_affinity (a replica in
#         # availability_zone) or az_affinity_with_primary (any node in availability_zone). default is none
#         mode: none
#         # availability_zone is this instance's zone, which the az_affinity modes require
#         availability_zone: ''
#         # replica_endpoints lists read replicas of a standard (single server) client
#         replica_endpoints: []
#       client_side_cache:
#         # enabled keeps recently read objects in this process, invalidated by the server. default is false
#         enabled: false
#         # mode is optin, where the server tracks the keys read through the cache, or broadcast, where it
#         # tracks every key under prefixes. default is optin
#         mode: optin
#         # prefixes are the key prefixes tracked in broadcast mode
#         prefixes: []
#         # size_bytes_per_connection is the cache budget of each connection to each node. default is 16MB
#         size_bytes_per_connection: 16777216
#         # max_ttl caps how long an object is kept; the server's TTL for it can shorten it. default is 30s
#         max_ttl: 30s

#     ## Configuration options when using a Filesystem Cache ###############
#     filesystem:
#       # cache_path defines the directory location under which the Trickster cache will be maintained
#       # default is /tmp/trickster
#       cache_path: /tmp/trickster
#       # min_free_bytes is the space to keep free on the filesystem that holds cache_path. when less is free, the
#       # cache evicts least-recently-accessed items as it does when it is over max_size_bytes. default is 0 (disabled)
#       min_free_bytes: 0

#     ## Configuration options when using a bbolt Cache ####################
#     bbolt:
#       # filename defines the file where the Trickster cache will be maintained
#       # default is trickster.db
#       filename: trickster.db
#       # bucket defines the name of the bbolt bucket (similar to a namespace) under which our key value store lives
#       # default is trickster
#       bucket: trickster

#     ## Configuration options when using a Badger cache ###################
#     badger:
#       # directory defines the directory location under which the Badger data will be maintained
#       # default is /tmp/trickster
#       directory: /tmp/trickster
#       # value_directory defines the directory location under which the Badger value log will be maintained
#       # default is /tmp/trickster
#       value_directory: /tmp/trickster

#     ## Configuration options when using cache chunking ###################
#     # Determines if cache chunking should be used. The following two options have no effect if false. Default value is false.
#     use_cache_chunking: true
#     # Determines the size of cache chunks that store timeseries data.
#     # Timeseries chunks are split by *duration*, not by literal size; the factor determines how large these chunks are
#     # based on the timestep of the provided query. Default value is 420.
#     timeseries_chunk_factor: 420
#     # Determines the size of cache chunks that store byterange data.
#     # Byterange chunks are split by literal size in bytes. Default value is 4096.
#     byterange_chunk_size: 4096

#   # Example of a second cache, sans comments, that backend configs below could use with: cache_name: bbolt_example

#   bolt_example:
#     provider: bbolt
#     bbolt:
#       filename: trickster.db
#       bucket: trickster

#     index:
#       reap_interval: 3s
#       flush_interval: 5s
#       max_size_bytes: 536870912
#       size_backoff_bytes: 16777216

# # Negative Caching Configurations
# # A Negative Cache is a map of HTTP Status Codes that are cached for the specified duration,
# # used for temporarily caching failures (e.g., 404s for 10 seconds)
# #
# # By default, each Origin Configuration maps to the default negative cache which you can
# # configure below, or can define your own negative caches, and specify them in your backend configs.
# # See /docs/negative-caching.md for more info.
# #

# negative_caches:
#   # default:
#   # The default negative cache config, mapped by all backends by default,
#   # is empty unless you populate it. Update it by adding entries here in the format of:
#   # "code": ttl

# #  Heres a pre-populated negative cache config ready to be uncommented and used in a backend config
# #  The general negative cache config will cache common failure response codes for 3 seconds
#   general:
#     "400": 3s
#     "404": 3s
#     "500": 3s
#     "502": 3s

# # IP access lists. Attach one with ip_acl_name on a listener, backend, or path.
# # See docs/ip-acl.md. Files are read when the configuration is loaded or reloaded; a reload is skipped while no
# # configuration file has changed, so touch a configuration file after editing only a list file.
# ip_acls:
#   office:
#     # match is longest (default) or ordered. longest uses the longest matching
#     # prefix, and deny wins when the same prefix is both allowed and denied.
#     match: longest
#     # default is the verdict when nothing matches. deny (default) or allow.
#     default: deny
#     allow: [10.0.0.0/8, 192.168.1.5, 2001:db8::/32]
#     deny: [10.0.99.0/24]
#     # allow_file and deny_file are one address or CIDR per line. Blank lines
#     # and lines whose first non-space character is # are skipped.
#     # allow_file: /etc/trickster/office-allow.lst
#     # deny_file: /etc/trickster/blocklist.lst
#     # source is client_ip (default) or peer. peer is listener scope only.
#     source: client_ip
#     # action is reject (default) or drop. drop is not valid on a backend or
#     # path that HTTP serves.
#     action: reject
#     # status is the HTTP status used when action is reject. 400-599; default 403.
#     status: 403
#   # ordered judges rules from top to bottom. allow, deny, and *_file are
#   # refused in this mode; each rule sets exactly one of them.
#   legacy:
#     match: ordered
#     default: deny
#     rules:
#       - deny: 10.1.2.0/24
#       - allow: 10.0.0.0/8
#       - deny: all

# # Named rate limiters. Attach one with rate_limiter_name on a listener, backend, or path.
# # See docs/rate-limiting.md. A path name replaces the backend limiter; none clears it.
# # The listener limiter is a separate outer layer and is never replaced.
# rate_limiters:
#   per-client:
#     # keys is 0 to 5 request attributes, in order. Empty means one bucket for everything.
#     keys: [client_ip]
#     # ipv6_prefix is how many leading bits of an IPv6 client address form client_ip. 1-128; default 64.
#     ipv6_prefix: 64
#     # algorithm accepts only sliding_window, which is the default.
#     algorithm: sliding_window
#     # limit is how many events each bucket may take in window.
#     limit: 600
#     # window is 1s to 1h; default 1m.
#     window: 1m
#     # missing_key is exempt (default) or shared.
#     missing_key: exempt
#     # action is reject (default), count, or close. close is stream listeners only.
#     action: reject
#     # response is the HTTP reply for reject. status is 400-599; default 429.
#     # headers overlay the defaults. Cache-Control: no-store is always kept.
#     response:
#       status: 429
#       headers:
#         Cache-Control: no-store
#       body: "Too Many Requests\n"
#     # policy_headers is none (default), ietf, or legacy.
#     policy_headers: none
#     # max_keys is how many buckets are tracked. Default 100000.
#     max_keys: 100000
#     # max_keys_action is allow (default) or reject when a new key does not fit.
#     max_keys_action: allow
#     # unit is requests, connections, sessions, or datagrams. Leave it unset when the
#     # limiter is attached on more than one plane.
#     # unit: requests

# Configuration options for mapping Origin(s)
backends:

  # # example static file server backend, which serves a local directory rather
  # # than proxying to an origin. paths, req_rewriter_name, origin_url and other
  # # proxying options are not valid for this provider.
  # website:
  #   provider: static
  #   hosts: [ www.example.com ]
  #   # authenticator_name optionally requires users to authenticate before any file is served
  #   # authenticator_name: example_auth_1
  #   # the static block, and its root, are required when the provider is static
  #   static:
  #     # root is the directory holding the content to serve. it must exist
  #     root: /var/www/html
  #     # default_file is served when a directory is requested. default is index.html
  #     default_file: index.html
  #     # cache_control is the Cache-Control header sent with every file. by default none is
  #     # sent, and clients judge a file's freshness from its Last-Modified time
  #     cache_control: no-cache
  #     # cache_control_by_extension overrides cache_control for matching files
  #     cache_control_by_extension:
  #       .js: public, max-age=31536000, immutable
  #       .css: public, max-age=31536000, immutable
  #     # response_headers are attached to every response
  #     response_headers:
  #       X-Content-Type-Options: nosniff
  #     # mime_types adds to and overrides the built-in Content-Types by file extension
  #     mime_types:
  #       .md: text/markdown; charset=utf-8
  #     # not_found_file is a file within the root served in place of a plain 404 response.
  #     # not_found_status is the status it is served with: 404 (the default) for an error
  #     # page, or 200 for a single-page application whose routes exist only in the browser
  #     not_found_file: errors/404.html
  #     not_found_status: 404
  #     # directory_listing lists a directory that has no default_file, rather than
  #     # answering it with a 404. default is false
  #     directory_listing: false
  #     # cache configures the fileserver cache, which holds small files in memory and drops
  #     # them when they change on disk. it is separate from, and unrelated to, the caches
  #     # configured in the caches section, and a static backend does not use a cache_name
  #     cache:
  #       # disabled serves every request from disk. default is false
  #       disabled: false
  #       # max_file_size_bytes is the largest file held in memory. default is 1048576 (1 MiB)
  #       max_file_size_bytes: 1048576
  #       # max_size_bytes is the most memory the cache will use, counting each held file
  #       # as its size plus 1 KiB of bookkeeping. default is 134217728 (128 MiB)
  #       max_size_bytes: 134217728
  #       # max_files is the most objects held (a file, and each compressed rendition of it, is
  #       # one), which also bounds the directories watched. the least recently used make room
  #       # for new ones once this or max_size_bytes is reached. default is 10000
  #       max_files: 10000
  #       # revalidation_interval is how often held files are compared to disk, as a
  #       # backstop to filesystem change events. default is 10s
  #       revalidation_interval: 10s

  # # example mysql backend, exposed by a listener with protocol mysql (see the
  # # listeners section). MySQL client connections to the listener are proxied
  # # to the origin. Exactly one mysql backend may map to a mysql listener.
  # mysql1:
  #   provider: mysql
  #   # origin_url uses the mysql scheme; the port defaults to 3306 if omitted
  #   origin_url: 'mysql://readonly:REDACTED@mysql-origin.example.com:3306/database'
  #   # Embedded passwords are redacted by sanitized configuration output and
  #   # YAML stringification. Protect the source file, which has the real value.
  #   # listener_names must reference a listener whose protocol is mysql
  #   listener_names: [mysql1]
  #   # MySQL listeners require a named authenticator. The authenticator's
  #   # users are used for downstream MySQL native-password authentication.
  #   authenticator_name: example_auth_1
  #   cache_name: default
  #   # timeout bounds both origin connect and query execution. Origin connection
  #   # admission remains one connection per downstream session.
  #   timeout: 1m
  #   max_concurrent_conns: 20
  #   max_object_size_bytes: 524288
  #   mysql:
  #     max_result_rows: 100000
  #     max_result_size_bytes: 67108864
  #   # Native health checks connect with the origin credentials and TLS
  #   # settings above, then execute COM_PING. HTTP matching options do not apply.
  #   healthcheck:
  #     interval: 5s
  #     timeout: 3s
  #   # Plaintext is accepted by default. When a full_chain_cert_path and
  #   # private_key_path are configured below, clients may upgrade in-band to
  #   # TLS. Set require_tls to reject plaintext downstream clients.
  #   require_tls: true
  #   tls:
  #     # Downstream server pair; MySQL upgrades in-band on the listener port.
  #     full_chain_cert_path: /etc/trickster/tls/server.crt
  #     private_key_path: /etc/trickster/tls/server.key
  #     # Upstream verified TLS; add both client fields for mutual TLS.
  #     certificate_authority_paths:
  #       - /etc/trickster/tls/origin-ca.crt
  #     client_cert_path: /etc/trickster/tls/origin-client.crt
  #     client_key_path: /etc/trickster/tls/origin-client.key
  #   # Deterministic SELECTs use OPC; supported cadence-aligned time-series
  #   # SELECTs use DPC. The common cache_name, timeseries_ttl,
  #   # timeseries_retention_factor, volatile_window, and
  #   # max_object_size_bytes backend settings apply.

  # # GreptimeDB serves HTTP and either or both native protocols. See
  # # examples/conf/greptimedb.yaml for the corresponding listeners/authenticator.
  # greptimedb1:
  #   provider: greptimedb
  #   origin_url: http://greptime.example:4000
  #   listener_names: [default, greptime-pg, greptime-mysql]
  #   authenticator_name: greptime-readers
  #   cache_name: default
  #   postgres:
  #     upstream_url: postgres://readonly:REPLACE_ME@greptime.example:4003/public
  #   mysql:
  #     upstream_url: mysql://readonly:REPLACE_ME@greptime.example:4002/public
  #
  # # example postgres backend, exposed by a listener with protocol postgres
  # # (see the listeners section). Provider timescaledb is an alias of postgres.
  # postgres1:
  #   provider: timescaledb
  #   # origin_url uses the postgres scheme; the port defaults to 5432 if omitted.
  #   # Embedded passwords are redacted by sanitized configuration output.
  #   origin_url: 'postgres://readonly:REDACTED@tsdb-origin.example.com:5432/database'
  #   # listener_names must reference a listener whose protocol is postgres
  #   listener_names: [postgres1]
  #   # With an authenticator, Trickster authenticates clients itself against
  #   # its users and logs in to the origin with the origin_url credentials.
  #   # Without one, the client's own authentication exchange is relayed to the
  #   # origin unchanged and the origin_url needs no credentials.
  #   authenticator_name: example_auth_1
  #   cache_name: default
  #   # timeout bounds both origin connect and the wait for a cached statement's result
  #   timeout: 1m
  #   max_concurrent_conns: 20
  #   postgres:
  #     # TLS toward the origin: disable (default), require, verify-ca or
  #     # verify-full, as libpq's sslmode. CAs and a client pair come from tls below.
  #     upstream_tls_mode: verify-full
  #     # a larger result is relayed to the client without being cached
  #     max_result_rows: 100000
  #     max_result_size_bytes: 67108864
  #   # The native health check logs in to the origin on a fresh connection with
  #   # the origin_url credentials and waits for ReadyForQuery; without origin
  #   # credentials it only confirms the origin accepts connections. HTTP
  #   # matching options do not apply.
  #   healthcheck:
  #     interval: 5s
  #     timeout: 3s
  #   # When a server certificate is configured, clients may upgrade in-band to
  #   # TLS. Set require_tls to refuse plaintext clients.
  #   require_tls: true
  #   tls:
  #     full_chain_cert_path: /etc/trickster/tls/server.crt
  #     private_key_path: /etc/trickster/tls/server.key
  #     certificate_authority_paths:
  #       - /etc/trickster/tls/origin-ca.crt
  #   # Deterministic SELECTs use OPC; time_bucket, date_bin and epoch-floor
  #   # time-series SELECTs use DPC. The common cache_name, timeseries_ttl,
  #   # timeseries_retention_factor, volatile_window, sharding and
  #   # max_object_size_bytes backend settings apply. proxy_only: true relays
  #   # every statement without inspecting it.

  # # example MoQ Transport relay backend, exposed by a listener with protocol
  # # moq (see the listeners section), and to browsers by WebTransport through
  # # an http listener with http3 enabled. One upstream subscription per track
  # # is shared by every downstream subscriber; the newest groups stay in memory
  # # and older ones spill to cache_name, which FETCH and fills read back.
  # moq1:
  #   provider: moq
  #   # a native QUIC origin (moqt://) or a WebTransport one (https://); omit
  #   # origin_url to serve only what publishers send
  #   origin_url: 'moqt://origin.example.com:443/live'
  #   # on an http listener, the backend's paths accept WebTransport sessions
  #   # (extended CONNECT) on the listener's HTTP/3 endpoint
  #   listener_names: [moq1, default]
  #   # matched against the AUTHORITY and PATH of a session's SETUP, or the
  #   # CONNECT request that opens a WebTransport session
  #   hosts: [live.example.com]
  #   cache_name: default
  #   # caps MAX_CACHE_DURATION, and is the lifetime of spilled groups of tracks that set none
  #   max_ttl: 1h
  #   moq:
  #     upstream:
  #       # in place of origin_url, an alb backend whose pool are moq backends
  #       # with origins: each track is subscribed through one member, a
  #       # strategy keyed on the flow (hrw) placing it by its full name, and a
  #       # track whose origin is lost moves to another member without its
  #       # subscribers noticing. The alb's mechanism is rr, p2c, hrw or lc;
  #       # stream.passive_health ejects members whose origins cannot be reached.
  #       # alb: origins
  #       # drafts offered to the origin, most preferred first
  #       drafts: [21, 20]
  #       # keep the upstream subscription forwarding while every subscriber is paused
  #       prewarm: false
  #       reconnect_backoff: 1s
  #       # keep an upstream subscription this long after its last subscriber leaves
  #       linger: 5s
  #       max_gap_fetches: 16
  #     live_edge:
  #       # groups of each track kept in memory
  #       groups: 3
  #       # payload bytes the live edge holds across all of the backend's tracks
  #       max_size_bytes: 67108864
  #     # false keeps only the live edge, so older groups are fetched from the origin
  #     spill: true
  #     # the wait for upstream fetches when a FETCH or fill names no FILL_TIMEOUT
  #     fill_timeout: 2s
  #     max_object_size_bytes: 67108864
  #     webtransport:
  #       # drafts accepted from WebTransport clients, most preferred first
  #       drafts: [22, 21, 20]
  #       # the draft assumed for a client offering no WT-Available-Protocols,
  #       # and for a WebTransport origin answering without WT-Protocol; 0
  #       # refuses both
  #       default_draft: 0
  #       # browser origins (scheme://host[:port]) that may open sessions, or
  #       # '*'; empty allows only an origin naming the requested host
  #       allowed_origins: []
  #       max_sessions: 10000
  #       # when the http listener stops, each WebTransport session gets a GOAWAY
  #       # naming this https URI to continue at; empty reuses the current one
  #       goaway_uri: ''
  #     publish:
  #       # accept PUBLISH and PUBLISH_NAMESPACE, making Trickster the origin of
  #       # what publishers send; open ingest belongs behind a network boundary
  #       enabled: false
  #       # namespace prefixes publishers may claim, as fields joined by '/',
  #       # such as live/studio; empty allows any
  #       namespaces: []
  #       max_publishers_per_track: 4
  #     authorization:
  #       # none admits every request; token requires an AUTHORIZATION_TOKEN
  #       # that token_file grants, one '<token> <publish|subscribe|any>
  #       # [namespace]' per line, read again whenever the file changes
  #       mode: none
  #   # the health check completes a SETUP exchange with the origin on a fresh session
  #   healthcheck:
  #     interval: 5s
  #   tls:
  #     # served to clients of the moq listener and the http listener's TLS port
  #     full_chain_cert_path: /etc/trickster/tls/server.crt
  #     private_key_path: /etc/trickster/tls/server.key
  #     # used toward the origin
  #     certificate_authority_paths:
  #       - /etc/trickster/tls/origin-ca.crt

  # # example VictoriaMetrics backend: MetricsQL through the Prometheus querying
  # # API and the Graphite APIs. See /docs/victoriametrics.md.
  # vm1:
  #   provider: victoriametrics
  #   # single-node VictoriaMetrics, or a tenant's vmselect path such as
  #   # http://vmselect:8481/select/0/prometheus
  #   origin_url: 'http://victoriametrics:8428'
  #   cache_name: default
  #   # keep it longer than the origin's -search.latencyOffset. default is 60s
  #   # volatile_window: 60s
  #   victoriametrics:
  #     # the upstream path of the Graphite APIs. By default it is the origin
  #     # URL's path, with a trailing /prometheus replaced by /graphite
  #     # graphite_path: /select/0/graphite
  #     # set when the origin runs with -search.disableCache, under which it
  #     # keeps the requested grid of long range queries. default is false
  #     # search_disable_cache: false
  #
  # # example graphite backend. Graphite is an ordinary HTTP backend; the
  # # settings below are the Graphite-specific ones. See /docs/graphite.md.
  # graphite1:
  #   provider: graphite
  #   origin_url: 'http://graphite.example.com:80'
  #   cache_name: default
  #   # Graphite is fetched at its native resolution so one cached series can
  #   # serve every panel width, which makes its responses larger and longer
  #   # than most providers'. These two therefore default to 64MB and 524288
  #   # points for graphite backends, rather than to the generic 512KB and
  #   # 1024, and only need setting here to override that. A response larger
  #   # than max_object_size_bytes cannot be delta-cached and is served
  #   # unaccelerated instead; a series longer than
  #   # timeseries_retention_factor is cropped and refetched.
  #   # max_object_size_bytes: 67108864
  #   # timeseries_retention_factor: 524288
  #   graphite:
  #     # time_zone interprets date-anchored from/until values (midnight,
  #     # today, MM/DD/YY) when a request carries no tz parameter. Set it to
  #     # the origin's graphite-web TIME_ZONE. default is UTC
  #     time_zone: UTC
  #
  #     # origin_username/origin_password supply a static HTTP Basic
  #     # credential sent as the Authorization header of every upstream
  #     # request (proxied, synthetic and health check alike). For non-Basic
  #     # schemes, set origin_authorization to the verbatim header value
  #     # (e.g., 'Bearer <token>') instead. unset by default
  #     # origin_username: 'metrics'
  #     # origin_password: '<the origin password>'
  #     # origin_authorization: 'Bearer <token>'
  #
  #     # passthrough_max_data_points forwards the client's maxDataPoints to
  #     # the origin instead of fetching at native resolution and
  #     # consolidating in Trickster. Requests carrying maxDataPoints are then
  #     # served unaccelerated, so the origin's consolidation is byte-identical.
  #     # Leave false unless you need that guarantee: true largely disables
  #     # acceleration for Grafana, which sends maxDataPoints on every panel.
  #     # default is false
  #     passthrough_max_data_points: false
  #
  #     # find_cache_ttl is how long a wildcard target's expansion to concrete
  #     # metric paths is reused before being refreshed from /metrics/expand.
  #     # Lower it if metrics appear and disappear frequently. default is 1m
  #     find_cache_ttl: 1m
  #
  #     # requests over either shape limit are served through the object
  #     # cache untouched rather than accelerated: max_targets_per_request
  #     # bounds the target count (default 128) and max_target_length one
  #     # target expression's bytes (default 16384)
  #     max_targets_per_request: 128
  #     max_target_length: 16384
  #
  #     # a wildcard expansion matching more leaves than max_expanded_leaves,
  #     # or more aggregate leaf-name bytes than max_expansion_bytes, is
  #     # likewise served through the object cache untouched
  #     max_expanded_leaves: 4096
  #     max_expansion_bytes: 2097152
  #
  #     # the resolution registry remembers each metric's archive ladder, so
  #     # that a query's step can be predicted without asking the origin
  #     resolution_registry:
  #       # ttl is how long a learned ladder is trusted. Whisper ladders only
  #       # change when an operator runs whisper-resize.py, so this is long.
  #       # default is 24h
  #       ttl: 24h
  #       # negative_ttl is the initial backoff after a failed resolution; it
  #       # doubles per consecutive failure, up to 10m. default is 30s
  #       negative_ttl: 30s
  #       # max_entries bounds each registry layer. default is 100000
  #       max_entries: 100000
  #       # persist writes learned ladders through to this backend's cache, so
  #       # a restart does not relearn them. default is true
  #       persist: true
  #       # probe_concurrency caps simultaneous ladder-learning runs.
  #       # default is 2
  #       probe_concurrency: 2
  #       # probe_budget caps the probes a single learning run may issue.
  #       # default is 96
  #       probe_budget: 96
  #
  #     # static_retentions seeds the registry with retentions matching your 
  #     # storage-schemas.conf. Entries are ordered and first-match-wins, exactly
  #     # as carbon applies them. This is a seed and an override, never the sole
  #     # source of truth: a match yields Configured confidence and is confirmed
  #     # by probe, and the probe wins when they disagree. That matters because
  #     # a Whisper file keeps whatever ladder it was created with, so
  #     # storage-schemas.conf and the files on disk routinely differ.
  #     static_retentions:
  #       - pattern: '^collectd\.'
  #         retentions: '10s:6h,1m:7d,10m:5y'
  #       - pattern: '.*'
  #         retentions: '1m:2d,5m:30d,1h:2y'

  # example backend named default. default is always created with these settings unless a different backend is defined here.
  # access this backend via http[s]://trickster-fqdn/default/ unless path_routing_disabled is true
  default:

    # listener_names maps this backend to compatible inbound listeners.
    # Unbound ordinary backends use default; mgmt and metrics are reserved.
    listener_names: [default]

    # ip_acl_name applies a named ip_acls entry to every route of this backend.
    # A path's ip_acl_name replaces it. none is not valid on a backend.
    # ip_acl_name: office

    # provider identifies the backend provider.
    # Valid options are: prometheus, influxdb, clickhouse, graphite, mysql, rule, alb,
    # reverseproxycache (or just rpc), or reverseproxy (or just rp)
    provider: prometheus

    # replica_group identifies the logical shard represented by this backend in
    # Time Series Merge pools. Backends with the same value are HA replicas.
    # When omitted, it defaults to this backend's name, making it a unique shard.
    # Replica Groups can only be set on TSM-compatible backends (currently
    # Prometheus) or nested ALBs used directly as members of a TSM pool.
    # replica_group: shard-a

    # for prometheus backends, you can configure label injection as follows:
    # prometheus:
    #   labels:
    #     labelname: value
    #   # flavor applies a Prometheus-compatible product's routes, limits and defaults.
    #   # cloudwatch: Amazon CloudWatch PromQL; amp: Amazon Managed Service for Prometheus.
    #   # See /docs/aws.md. mimir and thanos select the series_api below. Default is none.
    #   flavor: cloudwatch
    #   # series_api is how the backend serves raw series to an ALB using tsm global evaluation:
    #   # remote_read (the mimir flavor's default) or storeapi (the thanos flavor's default).
    #   # See /docs/prometheus.md#series-sources. Default is none.
    #   series_api: remote_read
    #   # series_endpoint is where series_api is served: an http(s) remote-read URL, by default the
    #   # origin_url path plus /api/v1/read, or the grpc:// or grpcs:// address StoreAPI requires
    #   series_endpoint: grpc://prometheus-sidecar:10901

    # origin_url provides the base upstream URL for all proxied requests to this origin.
    # it can be as simple as http://example.com or as complex as https://example.com:8443/path/prefix
    # origin_url is a required configuration value
    origin_url: http://prometheus:9090

#     # protocol selects the upstream wire protocol used to communicate with the origin.
#     # When empty (default), HTTP is used. Supported values are provider-specific:
#     #   clickhouse: 'native' — speak the native binary protocol to an upstream on port 9000
#     # This is independent of listeners, which select the inbound protocol.
#     protocol: ''

#     # h2c_prior_knowledge speaks cleartext HTTP/2 to the origin by prior
#     # knowledge, for origins that serve h2c only. Origins that speak HTTP/1.1
#     # will fail every request rather than degrade. Requires an http:// origin_url;
#     # an https origin already negotiates HTTP/2 via ALPN, and it cannot be combined
#     # with a non-HTTP upstream protocol such as clickhouse's 'native'.
#     # Default: false
#     h2c_prior_knowledge: false

#     # preserve_host sends the Host header exactly as the client sent it to the
#     # origin, instead of the origin's own host, and the client's Host then joins
#     # the cache key. A Host entry in a path's request_headers with a value, or a
#     # -Host entry, still replaces it and leaves the key alone; an empty Host
#     # entry changes nothing. Default: false
#     preserve_host: false

#     # origin_resolution selects how the origin host is resolved when dialing. With mode srv,
#     # the origin_url host (or a host set by a request rewriter) is a DNS SRV owner name, and
#     # each connection goes to a target and port from the SRV answer; the URL port is ignored.
#     # See docs/origin-resolution.md
#     origin_resolution:
#       # mode is a (default: A/AAAA lookup at the URL port) or srv. The settings
#       # below apply only to srv
#       mode: srv
#       # resolver is the host:port of a DNS server to query directly, which makes
#       # record TTLs visible. Default: empty, which uses the stdlib resolver
#       resolver: ''
#       # min_ttl and max_ttl clamp how long an answer is cached. max_ttl also bounds
#       # how long the last good answer keeps serving while lookups fail. Defaults: 5s, 60s
#       min_ttl: 5s
#       max_ttl: 60s
#       # negative_ttl is how long NXDOMAIN or an empty answer is cached. Default: 5s
#       negative_ttl: 5s
#       # tls_server_name is owner (default: verify an https origin against the URL host)
#       # or target (verify against the dialed SRV target)
#       tls_server_name: owner

    # is_default describes whether this backend is the default backend considered when routing http requests
    # it is false, by default; but if you only have a single backend configured, is_default will be true unless explicitly set to false
    is_default: true

#     # max_query_range specifies the maximum allowed query range duration for this backend (e.g. 1h, 1d, 14d).
#     # Setting this value restricts clients from making oversized queries.
#     # default is empty (disabled)
#     max_query_range: 14d

#     # hosts indicates which FQDNs requested by the client should route to this Origin (in addition to path-based routing)
#     # if you are using TLS, all FQDNs should be included in the certfiicate common names to avoid insecure warnings to clients
#     # matching is case-insensitive; a single-label wildcard like *.example.com is also accepted
#     # default setting is empty list. List format is: hosts: [ 1.example.com, 2.example.com ]
#     # an entry may be a one-label wildcard (*.example.com matches api.example.com) or an
#     # any-depth wildcard (**.example.com also matches a.b.example.com); see /docs/paths.md
#     hosts: []

#     # cache_name identifies the name of the cache (configured above) that you want to use with this backend. default is default
#     cache_name: default

#     # forwarded_headers indicates whether Trickster should use Forwarded, X-Forwarded-*
#     # or no forwarded headers when communicating with backends. A Via header is always sent,
#     # regardless of this values setting.
#     # Hops a request arrived with are appended to only when one of the listener's
#     # trusted_proxies sent it; from any other peer they are replaced by Trickster's hop.
#     # Options are standard, x, both, or none; default is standard
#     forwarded_headers: standard

#     # cors controls Access-Control-* response headers for this backend. When omitted, Trickster retains
#     # its legacy Access-Control-Allow-Origin: '*' behavior. Modes are preserve, merge, replace, and disable.
#     # See /docs/cors.md for mode behavior, path overrides, and cache-key handling.
#     cors:
#       mode: replace
#       headers:
#         Access-Control-Allow-Origin: https://dashboard.example.com

#     # cache_key_prefix defines the prefix this backend appends to cache keys. When using a shared cache like Redis,
#     # this can help partition multiple trickster instances that may have the same same hostname or ip address (the default prefix)
#     cache_key_prefix: example

#     # negative_cache_name identifies the name of the negative cache (configured above) to be used with this backend. default is default
#     negative_cache_name: default

#     # path_routing_disabled will prevent the backend from being accessible via /backend_name/ path to Trickster. Disabling this requires
#     # the backend to have hosts configured (see below), any_host_routing enabled, or be the target of a rule backend,
#     # or it will be unreachable. default is false
#     path_routing_disabled: false

#     # any_host_routing registers this backend's paths for every hostname reaching its listeners, rather than for a
#     # hosts list. It cannot be combined with hosts. default is false
#     any_host_routing: false

#     # path_defaults_disabled registers only the paths configured below, suppressing the paths the backend's provider
#     # defines by default (such as the catch-all '/' route, and a time series provider's API paths). default is false
#     path_defaults_disabled: false

#     # access_log configures per-backend HTTP access and error logging. Both logs are off by default and
#     # are each enabled by setting their filename. See docs/access-logs.md for all options and format tokens
#     access_log:
#       # filename enables the access log (one line per request served by this backend)
#       filename: /var/log/trickster/example.access.log
#       # format is a named preset (common, combined, extended, json) or a custom Apache-style
#       # %-token format string. default is combined
#       format: combined
#       # rotation controls when the log is rotated; a rotation occurs when either threshold is reached
#       rotation:
#         # size rotates the log when the live file would exceed this size. default is 256MB
#         size: 256MB
#         # interval rotates the log when the live file is older than this. default is 0 (off)
#         interval: 1d
#       # retention controls how many rotated archives (example.access.log.1.gz, .2.gz, ...) are kept
#       retention:
#         # count is the maximum archives kept; 0 is unlimited. default is 80
#         count: 3
#         # age prunes archives older than this. default is 7d
#         age: 7d
#       # compress gzips rotated archives. default is true
#       compress: true
#       # error_filename enables the error log, receiving requests whose response status is >= error_threshold
#       error_filename: /var/log/trickster/example.error.log
#       # error_threshold is the minimum response status code written to the error log. default is 400
#       error_threshold: 400
#       # extra declares static values rendered by %{key}e tokens and the json preset's extra object
#       extra:
#         team: payments
#       # error_format, error_rotation, error_retention and error_compress override the error log's
#       # behaviors; each inherits from the corresponding access log option above when unset
#       error_format: ''

#     # rule_name provides the name of the rule config to be used by this backend.
#     # This is only effective if the provider is rule
#     rule_name: example-rule

#     # req_rewriter_name is the name of a configured rewriter (in the request_rewriters key) that modifies the request prior to
#     # processing by the backend client
#     req_rewriter_name: example-rewriter

#     # tracing_name selects the distributed tracing configuration (crafted below) to be used with this backend. default is default
#     tracing_name: default

#     # geo_acl_name names a geo ACL (in the geo_acls key, below) that judges this backend's clients by where they are,
#     # on every listener that serves it. A path's geo_acl_name replaces it, and geo_acl_name: none on a path clears it.
#     # A member of an alb that serves a native protocol, tcp, tls or udp listener may not name one; set it on the alb.
#     geo_acl_name: north-america

#     # dearticulate_upstream_ranges, when true, instructs Trickster to make multiple parallel requests to the backend for each
#     # range needed to fulfill the client request, rather than making a multipart range request. default is false
#     # This setting applies only to object request byte ranges and not time series requests (they are always dearticulated)
#     dearticulate_upstream_ranges: false

#     # multipart_ranges_disabled, when true, instructs Trickster to return the full object when the client provides
#     # a multipart range request. This setting applies only to object request byte ranges and not time series requests.
#     # The default is false.
#     multipart_ranges_disabled: false

#     # compressible_types defines the Content Types that will be compressed when stored in the Trickster cache
#     # or sent to a client. reasonable defaults are set, so use this with care. To disable compression, set
#     # compressible_types: []
#     # The encoding used is the one the client's Accept-Encoding header weights highest (q) of those
#     # Trickster supports (zstd, br, gzip, deflate). Among equal weights, or when the client gives none,
#     # Trickster prefers them in that order. A wildcard (*) stands for the encodings the client didn't
#     # name. An encoding the client refuses (q=0), or weights below identity, is never used.
#     # Default list is provided here:
#     compressible_types: [ text/javascript, text/css, text/plain, text/xml, text/json, application/json, application/javascript, application/xml ]

#     # timeout defines how long Trickster will wait before aborting an upstream http request. Default: 60s
#     timeout: 60s

#     # keep_alive_timeout defines how long Trickster will wait before closing a keep-alive connection due to inactivity
#     # if the origins keep-alive timeout is shorter than Tricksters, the connect will be closed sooner. Default: 120s
#     keep_alive_timeout: 120s

#     # max_idle_conns set the maximum concurrent keep-alive connections Trickster may have opened to this backend
#     # while no clients are being served. Default: 20
#     max_idle_conns: 20

#     # max_concurrent_conns set the maximum number of concurrent connections Trickster may have opened to this backend
#     # additional requests will be queued. Default: 20
#     max_concurrent_conns: 20

#     # max_ttl defines the maximum allowed TTL for any object cached for this backend. default is 24 hours
#     max_ttl: 24h

#     # revalidation_factor is the multiplier for object lifetime expiration to determine cache object TTL; default is 2
#     # for example, if a revalidatable object has Cache-Control: max-age=300, we will cache for 10 minutes (300s * 2)
#     # so there is an opportunity to revalidate
#     revalidation_factor: 2.0

#     # max_object_size_bytes defines the largest byte size an object may be before it is uncacheable due to size. default is 524288 (512k),
#     # or 67108864 (64M) for an ALB with mechanism: tsm
#     max_object_size_bytes: 524288

#     # max_capture_bytes caps the per-response in-memory capture buffer used by ALB fanout and Prometheus
#     # transform/label handlers. A member whose body exceeds the cap is treated as a partial failure
#     # (X-Trickster-Result: phit) rather than truncating the merged response silently. default is 268435456 (256 MiB)
#     max_capture_bytes: 268435456

#     # These next settings only apply to Time Series backends

#     # step_alignment selects what the backend does with partial buckets at the edges of a query's time range:
#     # truncate, drop, partial, partial_start, partial_end or off. The provider's default applies when it is unset.
#     # off sends each query to the origin with its range as the client sent it, and caches the response as an
#     # object for one minute, keyed on that range.
#     # On an alb, step_alignment applies one mode to every pool member's HTTP requests. A tsm alb without it
#     # applies its first configured member's mode, so that the members it merges answer on one grid.
#     # step_alignment: truncate

#     # volatile_window prevents new datapoints that fall within the window (relative to time.Now) from being permanently
#     # cached. Think of it as "the newest N milliseconds of real-time data are preliminary and subject to updates, so refresh them periodically"
#     # default is 0ms
#     volatile_window: 0ms

#     # volatile_window_points works like the duration version, except the methodology is based on # of intervaled timestamps (points) in the series
#     # instead of a relative time. You can set both values and the one impacting the most number of elements in the time series takes precedence.
#     volatile_window_points: 0

#     # timeseries_retention_factor defines the maximum number of recent timestamps to cache for a given query. Default is 1024
#     timeseries_retention_factor: 1024

#     # timeseries_ttl defines the relative expiration of cached timeseries. default is 6 hours (21600 seconds)
#     timeseries_ttl: 6h

#     # timeseries_eviction_method selects the metholodogy used to determine which timestamps are removed once
#     # the timeseries_retention_factor limit is reached. options are oldest and lru. Default is oldest
#     timeseries_eviction_method: oldest

#     # fast_forward_disable, when set to true, will turn off the fast forward feature for any requests proxied to this backend.
#     # For Prometheus it is the same as step_alignment: truncate, and it cannot be set alongside step_alignment
#     fast_forward_disable: false

#     # partial_bucket_ttl defines the relative expiration of cached partial buckets, including fast forward data. default is 15s.
#     # The former name, fastforward_ttl, is still accepted when partial_bucket_ttl is not set
#     partial_bucket_ttl: 15s

#     # shard_max_size_points defines the maximum size of a timeseries request in unique timestamps,
#     # before sharding into multiple requests of this denomination and reconsitituting the results.
#     # If shard_max_size_points and shard_max_size_time are both > 0, the configuration is invalid.
#     # default is 0
#     shard_max_size_points: 0

#     # shard_max_size_time defines the max size of a timeseries request in arbitrary time units (ns, ms, s, h, d),
#     # before sharding into multiple requests of this denomination and reconsitituting the results.
#     # If shard_max_size_time and shard_max_size_points are both > 0, the configuration is invalid.
#     # default is 0ms
#     shard_max_size_time: 0ms

#     # shard_step defines the epoch-aligned cadence to use when creating shards. When set to 0,
#     # shards are not aligned to the epoch at a specific step. shard_max_size_time must be perfectly
#     # divisible by shard_step when both are > 0, or the configuration is invalid.
#     # default is 0ms
#     shard_step: 0ms

#     # Simulated Latency
#     # set latency_min > 0 to apply a consistent latency to each request to this backend
#     # set latency_max > latency_max (which can be 0) to apply a random latency between the two
#     latency_max = 0
#     latency_max = 0

#     #
#     # Each backend provider implements their own defaults for health checking
#     # which can be overridden per backend configuration. See /docs/health.md for more information
#     healthcheck:

#       # interval, timeout, failure_threshold, and recovery_threshold apply to
#       # HTTP and native-protocol probes. The remaining options in this section
#       # apply only to HTTP health checks.

#       ## Crafting a Heatlh Check

#       # verb is the HTTP Method Trickster will when performing an upstream health check for this backend
#       # default is GET for all backend types unless overridden per-backend here.
#       verb: GET

#       # scheme is either http or https
#       # default is http
#       scheme: https

#       # host defines a custom Host header to include in health check requests
#       # default is the hostname in the backend configuration's origin_url
#       host: alternate-host.example.com

#       # port defines a custom port to include in health check requests
#       # default is 80 or 443 depending upon scheme
#       port: 8080

#       # path is the URL Trickster will request against this backend to
#       # when a health check request is received by Trickster via http://<trickster-endpoint>/trickster/<backend_name>/health 
#       # this is the default value for prometheus:
#       path: /api/v1/query

#       # query is the query string Trickster will append the when performing an upstream health check for this backend
#       # This example value is the default for prometheus (again, see /docs/health.md)
#       query: query=up

#       # headers provides a list of HTTP Headers to add to Health Check HTTP Requests to this backend
#       # default is none
#       headers:
#         Authorization: Basic SomeHash

#       # body provides a body to use with the health check request when the method is POST or PUT
#       # default is empty string, and is ignored for non-Body-based methods
#       body: "my health check request body"

#       ## Crafting a Healthy Response Profile

#       # timeout is the maximum during the health checker will wait for a response before aborting the check
#       # default is 3s
#       timeout: 3s

#       # expected_codes is the list of acceptable HTTP response codes when health checking the backend
#       # for considering the backend healthy
#       # default is [ 200 ]
#       expected_codes: [ 200, 204, 206, 301, 302, 304 ]

#       # expected_headers is the list of required HTTP response headers when health checking the backend
#       # for considering the backend healthy
#       # default is empty set
#       expected_headers:
#         X-Health-Check-Status: success

#       # expected_body is the response body string a health check response must provide
#       # for considering the backend healthy
#       # default is not checked
#       expected_body: "health check pass."

#     # the paths section customizes the behavior of Trickster for specific paths for this Backend. See /docs/paths.md for more info.
#     paths:
#       - path: /public/
#         # ip_acl_name replaces the backend list. none clears it for this path.
#         # The listener list still applies. See docs/ip-acl.md
#         ip_acl_name: none
#       - path: /api/v1/admin/
#         methods: [ '*' ]                                 # HTTP methods to be routed with this path config. * for all methods.
#         match_type: prefix                             # match $path* (using exact will match just $path)
#         handler: localresponse                         # dont actually proxy this request, respond immediately
#         response_code: 401
#         response_body: 'No soup for you!'
#         no_metrics: true                                 # do not record metrics for requests to this path
#         hide_result_header: true                         # withhold X-Trickster-Result from the client; the access log still records it
#         response_headers:
#           Cache-Control: no-cache                  # attach these headers to the response down to the client
#           Content-Type: text/plain
#         cors:                                      # overrides the backend CORS policy for this path
#           mode: disable                            # remove all Access-Control-* response headers
#       # a path may be conditioned on request headers and query parameters; conditioned
#       # paths on one path are tried in order, so list an unconditioned one after them
#       - path: /example/
#         methods: [ GET ]
#         match_type: segment                  # prefix matching on a segment boundary: /example and /example/x
#         handler: proxy
#         match_headers:                       # every listed condition must be satisfied
#           - name: X-Tenant
#             value: gold                      # compared to the whole header value
#         match_query_params:
#           - name: version
#             value: '^v[0-9]+$'
#             regex: true                      # matched as an unanchored RE2 regular expression
#         match_order: 1                       # ranks conditioned paths sharing a path and method, lowest first;
#                                              # needed when the candidates come from different backends
#       - path: /example/
#         methods: [ GET, POST ]
#         collapsed_forwarding: progressive    # see /docs/collapsed_forwarding.md
#         match_type: prefix                   # this path is routed using prefix matching
#         handler: proxycache                  # this path is routed through the cache
#         req_rewriter_name: example-rewriter  # name of a rewriter to modify the request prior to handling
#         geo_acl_name: europe                 # replaces the backend's geo ACL for this path; none clears it
#         cache_key_params: [ ex_param1, ex_param2 ]       # the cache key will be hashed with these query parameters (GET)
#         cache_key_form_fields: [ ex_param1, ex_param2 ]  # or these form fields (POST)
#         cache_key_headers: [ X-Example-Header ]            # and these request headers, when present in the incoming request
#         request_headers:
#           Authorization: custom proxy client auth header
#           -Cookie: ''                                # attach these request headers when proxying. the + in the header name
#           +Accept-Encoding: gzip                   # means append the value if the header exists, rather than replace
#                                                               # while the - will remove the header
#         request_params:
#           +authToken: SomeTokenHere                 # manipulate request query parameters in the same way
#       # a dispatch-only path lives on this backend's own router and on no
#       # listener: it is reachable only when an ALB pool or a rule's
#       # next_route hands a request to this backend. See /docs/paths.md.
#       - path: /internal/
#         match_type: prefix
#         methods: [ '*' ]
#         handler: proxy
#         dispatch_only: true
#       # a path may bound and retry its upstream exchange, mirror its requests
#       # to another backend, and relay origin trailers on a caching handler.
#       # See the Timeouts and Retries, Mirroring Requests and Forwarding
#       # Trailers sections of /docs/paths.md
#       - path: /orders/
#         match_type: prefix
#         methods: [ GET, POST ]
#         handler: proxycache
#         timeout: 5s                          # deadline on the whole upstream exchange, retries included
#         attempt_timeout: 2s                  # deadline on each upstream attempt; at most timeout
#         retry:
#           attempts: 2                        # additional attempts after a failure (1-10)
#           codes: [ 502, 503 ]                # upstream statuses retried; connection failures always are
#           backoff: 100ms                     # wait before each retry
#           budget_percent: 20                 # retries allowed as a share of recent requests. default 20
#         mirrors:
#           - backend_name: shadow             # backend receiving a copy of each request; its responses are discarded
#             percent: 10                      # share of requests copied. default 100
#             max_in_flight: 64                # copies in progress at once; more are dropped. default 64
#       # regex path: a path starting with ^/ is auto-detected as a regular expression
#       # (RE2 syntax); or set match_type: regex explicitly. Regex paths are evaluated
#       # only after exact and prefix matching both miss, longest pattern first.
#       # See the Regex Paths section of /docs/paths.md, including the catch-all caveat.
#       - path: '^/api/[0-9]+/results'
#         methods: [ GET ]
#         handler: proxycache

#         # the tls section configures the frontend and backend TLS operation for the backend
#     tls:
#         # TLS Frontend Configs
#         # You can configure which certificate and key to use when this endpoint serves downstream clients over TLS
#         # Trickster will fail out at startup if the provided files do not exist, are unreadable, or in an invalid format
#         # These settings by default are '' (empty string), which disables this backend from being routed over the TLS port
#         full_chain_cert_path: /path/to/your/cert.pem
#         private_key_path: /path/to/your/key.pem

#         # acme obtains and renews this backend's certificates from an issuer in the top-level acme
#         # section, in place of full_chain_cert_path and private_key_path. domains defaults to hosts
#         # acme:
#         #   issuer: letsencrypt
#         #   domains: [ www.example.com ]

#         # TLS Backend Configs
#         # These settings configure how Trickster will behave as a client when communicating with
#         # this backend over TLS
        
#         # if insecure_skip_verify is true, Trickster will trust the origins certificate without any verification
#         # default is false
#         insecure_skip_verify: false
        
#         # certificate_authority_paths provides a list of additional certificate authorities to be used to trust an upstream origin
#         # in addition to Operating System CAs.  default is an empty list, which insructs the Trickster to use only the OS List
#         certificate_authority_paths: [ ../../testdata/test.rootca.pem ]

#         # certificate_authority_pem adds certificate authorities the same way, from a PEM bundle written
#         # inline rather than read from a file. default is empty
#         # certificate_authority_pem: |
#         #   -----BEGIN CERTIFICATE-----
#         #   ...
#         #   -----END CERTIFICATE-----

#         # server_name is the hostname sent as SNI and verified against the origin's certificate, when it
#         # differs from the origin_url host. default is empty, which uses the origin_url host
#         # server_name: origin.internal.example.com

#         # exclude_system_roots makes the configured certificate authorities the only trusted ones for
#         # this origin rather than additions to the OS roots; requires at least one to be configured.
#         # default is false
#         # exclude_system_roots: false
        
#         # client_cert_path provides the path to a client certificate for Trickster to use when authenticating with an upstream server
#         # empty string '' by default
#         client_cert_path: /path/to/my/client/cert.pem
        
#         # client_key_path provides the path to a client key for Trickster to use when authenticating with an upstream server
#         # empty string '' by default
#         client_key_path: /path/to/my/client/key.pem

#   # For multi-backend support, backends are named, and the name is the second word of the configuration section name.
#   # In this example, backends are named foo-01.example.com and foo-02.example.com.
#   # Clients can indicate this backend in their path (http://trickster.example.com:8480/foo/api/v1/query_range?.....)
#   # unless path_routing_disabled: true
#   # there are other ways for clients to indicate which backend to use in a multi-backend setup. See the documentation for more information

#   foo-01.example.com:
#     is_default: false
#     provider: reverseproxy
#     origin_url: http://foo-origin-01
#     healthcheck:
#       interval: 1s

#   foo-02.example.com:
#     is_default: false
#     provider: reverseproxy
#     origin_url: http://foo-origin-02
#     healthcheck:
#       interval: 1s

# # InfluxDB 3.x backend example. See /docs/influxdb.md for full details
# # (v3 HTTP API: /api/v3/query_sql, /api/v3/query_influxql, /api/v3/write_lp;
# # v1/v2 compatibility endpoints also work against the same backend).
#
#   influx3:
#     is_default: false
#     provider: influxdb
#     origin_url: 'http://influxdb3:8181/'
#
#     # Mapping a flight-sql-protocol listener (see the listeners section)
#     # exposes this backend over Apache Arrow Flight SQL (gRPC): Trickster
#     # proxies Flight SQL queries, metadata RPCs (GetTables/Schemas/etc.) and
#     # the full prepared-statement lifecycle, caching the Arrow IPC byte
#     # stream. Omit the flight listener name to serve HTTP only.
#     listener_names: [ default, influx3-flight ]
#
#     # influxdb holds InfluxDB-specific backend options.
#     influxdb:
#       # flight_upstream_address overrides the upstream Flight SQL address.
#       # Defaults to the host:port from origin_url when empty.
#       flight_upstream_address: 'influxdb3:8181'
#       # flight_upstream_tls dials the upstream Flight SQL endpoint with TLS,
#       # honoring the backend tls block's insecure_skip_verify.
#       flight_upstream_tls: false
#       # flight_max_response_bytes bounds one buffered upstream response;
#       # flight_max_buffered_bytes bounds concurrent assembly and streaming.
#       flight_max_response_bytes: 134217728
#       flight_max_buffered_bytes: 536870912
#       # Alternate endpoint authorities must be explicitly trusted because
#       # client credentials are forwarded to them. Connections are capped.
#       flight_allowed_location_hosts: [ 'influxdb3-replica:8181' ]
#       flight_max_location_clients: 16
#       # flight_cache_ttl bounds the lifetime of Flight SQL object-tier
#       # entries (whole responses cached verbatim). Delta-cached time-series
#       # entries use the backend's timeseries_ttl instead.
#       flight_cache_ttl: 60s

# # Application Load Balancer Backend configuration options, see /docs/alb.md for more information
#
#   alb01:
#     hosts: [ foo.example.com ]
#     path_routing_disabled: true # only route to the alb via the foo.example.com Host header
#     provider: alb
#     alb:
#       # mechanism defines the ALB pool member selection mechanism.
#       # rr (round_robin), p2c (power_of_two_choices), lc (least_connections), lt (least_time)
#       # and hrw (highest_random_weight) select one pool member per request; fr (first_response),
#       # fgr (first_good_response), nlm (newest_last_modified) and tsm (time_series_merge) fan each
#       # request out to the pool; ur (user_router) routes by user. race (connect_race) and mirror
#       # (udp_mirror) serve only tcp/tls and udp stream listeners. See /docs/alb.md.
#       # values are rr, fr, fgr, nlm, or tsm. see the docs for detailed descriptions of each
#       # rr - standard round robin
#       # fr - fanout and return the First Response regardless of status code
#       # fgr - fanout and return the First Good Response based on status code
#       # nlm - fanout and return the Response with the Newest Last-Modified header
#       # tsm - fanount and perform a Time Series Merge of the results into a single time series
#       # ur - inspect the credentials in the Request and routes it based on the Username

#       mechanism: rr # use a basic round robin

#       # pool defines the pool of backends to which the alb routes
#       # use the two example backends above
#       pool: [ foo-01.example.com, foo-02.example.com ]
#
#       # pool entries optionally carry an integer weight for the round robin
#       # mechanism (default 1); apportionment is exact. e.g.:
#       # pool:
#       #   - foo-01.example.com
#       #   - name: foo-02.example.com
#       #     weight: 3 # receives 3 of every 4 requests
#       #
#       # a backup entry stands by: it is used only while no other pool member is healthy. e.g.:
#       # pool:
#       #   - foo-01.example.com
#       #   - name: foo-02.example.com
#       #     backup: true
#       #
#       # a draining entry takes no new work, but keeps the sticky sessions it already has. e.g.:
#       # pool:
#       #   - foo-01.example.com
#       #   - name: foo-02.example.com
#       #     drain: true

#       # healthy_floor is the minimum health status for a Backend to be considered healthy in the pool
#       #  1 indicates only backends positively reporting as healthy are included
#       #  0 indicates backends in either a unknown/unchecked state or healthy reporting state
#       # -1 includes all backends, regardless of reporting state
#       # default is 0
#       healthy_floor: 0

#       # propagate_health makes this ALB report itself unavailable, to any ALB that has it as a pool
#       # member, while it has no healthy member of its own. default is false: it keeps its share
#       propagate_health: false

#       # max_capture_bytes overrides the backend-level max_capture_bytes for this ALB's fanout members.
#       # Set this when the ALB's expected response shape differs from the backend default. When 0 (the
#       # default), the parent Backend's max_capture_bytes is used, falling back to 268435456 (256 MiB).
#       # With tsm evaluation: global, it bounds each member's raw series response and each evaluation's
#       # encoded result; a larger result fails with a 422 execution error rather than being returned in part.
#       max_capture_bytes: 16777216 # 16 MiB
#       fgr: # First Good Response mechanism options, only applicable when mechanism is set to fgr
#         # status_codes is a list of status codes considered 'good' when using the fgr mechanism
#         # when this is not set, any response code < 400 is considered good. Use this setting to
#         # provide an explicit list. An entry is a single code or an inclusive range, e.g.:
#         # status_codes: [ { start: 200, end: 299 }, 304 ]
#         status_codes: [ 200 ] # this would consider only 200 OK's good, and not 204, 302, etc.

#       hrw: # Highest Random Weight mechanism options, only applicable when mechanism is set to hrw
#         # key is what a client's affinity follows: client_ip (default), host, header:<name>,
#         # cookie:<name> or query:<name>. Requests sharing a key reach the same pool member.
#         # A stream listener can read client_ip, sni (the TLS server name) when it is tls, and
#         # proxy_tlv:<type> (a PROXY protocol v2 TLV, e.g. proxy_tlv:0xEA) when it accepts the
#         # PROXY protocol. A native protocol listener, such as mysql, can read client_ip and user.
#         key: client_ip
#         # ipv6_prefix is how many leading bits of an IPv6 client address form a client_ip key.
#         # default is 64, which keeps a client that rotates its privacy address on one member
#         ipv6_prefix: 64

#       lt: # Least Time mechanism options, only applicable when mechanism is set to lt
#         # decay is how quickly a member's latency average follows a change. default is 10s
#         decay: 10s
#         # status_codes lists the response codes that count as a good answer; any other records
#         # a latency penalty, so a member that fails fast never looks fast. Entries are single
#         # codes or inclusive ranges. default is every code except 502, 503 and 504
#         status_codes: [ { start: 100, end: 501 }, { start: 505, end: 599 } ]
#         # signal is what is timed. The default depends on the listener: first_write on http (the
#         # first byte sent to the client), connect on tcp and tls (or first_byte), first_reply on udp
#         signal: first_write

#       sticky: # keeps each client on the member it was first sent to; rr, p2c, lc, lt and hrw only
#         # mode is how a client's member is remembered: cookie (a signed token in a cookie),
#         # header (the same token in a header, for API clients) or table (a table kept by the ALB,
#         # by a key read from each request, connection or session). Unset, the default, is cookie
#         # on http listeners and table on tcp, tls, udp and native ones, and allows a cookie and a
#         # table block; a mode that is set allows only its own block, and cookie or header is
#         # refused on a listener that is not http
#         # mode: cookie
#         # ttl is a session's lifetime from its first request; 0 is no limit, and a browser-session
#         # cookie. default is 1h
#         ttl: 1h
#         # idle ends a session left unused. A token counts it from when it was last issued and
#         # is reissued after half of it, so an unused session ends between idle/2 and idle after its
#         # last request; a table entry counts it from its last use. default is 0: never
#         idle: 0
#         # on_unavailable is repick (default), to move a session whose member is unavailable, or
#         # reject, to answer 503, or refuse a connection, until its member is available again
#         on_unavailable: repick
#         # secret signs cookie and header tokens: at least 32 bytes, the same on every replica.
#         # secret_file reads it from a file instead. with neither, a random per-process key is used
#         # secret_file: /etc/trickster/sticky.key
#         cookie:
#           name: trickster_sticky  # default
#           path: /                 # default
#           secure: auto            # auto (default) marks it Secure over TLS; or true, false
#           http_only: true         # default
#           same_site: lax          # lax (default), strict or none (requires secure: true)
#           lifetime: permanent     # permanent (default) sets Max-Age from the token; session never does
#           mark_private: false     # true adds Cache-Control: private to a response that sets it
#         # header: # header mode only
#         #   name: X-Trickster-Session
#         # table: # table mode only
#         #   key: client_ip        # any hrw.key value the ALB's listeners can read
#         #   learn: request        # response also remembers a header:/cookie: value a member sets
#         #   ipv6_prefix: 64
#         #   max_entries: 100000

#       stream: # only for an ALB that serves a tcp, tls or udp listener. See /docs/alb.md
#         # connect_retries is how many other pool members a tcp or tls connection is offered when
#         # it cannot connect to the one it was given. default is 0: the connection is refused
#         connect_retries: 0
#         # passive_health ejects a member after repeated failures to connect to it, without
#         # waiting for a health check. It is off unless this block is present
#         passive_health:
#           failures: 3               # consecutive failed connects that eject a member
#           eject: 30s                # how long it stays out
#           max_ejected_percent: 50   # never more of the pool than this, and never its last member
#         # race_width is how many pool members the race mechanism connects to at once, 2 to 8.
#         # default is every member, up to 4. connect_retries and passive_health do not apply to
#         # the race and mirror mechanisms
#         # race_width: 2

#       tsm: # Time Series Merge mechanism options, only applicable when mechanism is set to tsm
#         # evaluation is merge (default), which merges the members' answers, or global, which
#         # evaluates each query once over every member's deduplicated raw series, as Thanos does.
#         # Every member of a global ALB needs a prometheus series_api. See /docs/alb.md#global-evaluation
#         evaluation: merge
#         # the settings below apply only with evaluation: global
#         # replica_labels are left out of a raw series' identity, so series differing only by them
#         # are copies of one series. default is none
#         # replica_labels: [ replica ]
#         # deduplication is penalty (default), which follows one replica across gaps as Thanos
#         # does, or chain, which keeps every distinct timestamp of every replica
#         # deduplication: penalty
#         # partial_response answers from the members that could be read, with a warning, when
#         # one can't. a request's partial_response parameter overrides it. default is true
#         # partial_response: true
#         # max_samples bounds the samples one evaluation holds at once. default is 50000000
#         # max_samples: 50000000
#         # query_timeout bounds one evaluation, including its wait for a slot. default is 2m
#         # query_timeout: 2m
#         # max_concurrent_queries bounds the evaluations the ALB runs at once. default is 20
#         # max_concurrent_queries: 20
#         # max_fetched_series and max_fetched_samples bound the raw series and samples one
#         # evaluation reads, before deduplication. default is 0, unlimited
#         # max_fetched_series: 0
#         # max_fetched_samples: 0
#         # raw_cache_window is how far back from now the members' raw series are cached; older
#         # samples are read from the members by every evaluation. default is 31d
#         # raw_cache_window: 31d
#         # the newest 5m of a mimir or thanos member's raw series, and none of another member's, are
#         # read again by every evaluation, unless the ALB sets volatile_window for all of them

# # ALB Pool Autodiscovery - see /docs/alb-autodiscovery.md for more information
# #
# # An ALB's pool membership can be discovered and kept current at runtime from
# # Kubernetes, DNS SRV or A/AAAA records, or a watched member-list file.
# # Discovered members are cloned from a designated template backend. Three
# # config parts work together: a named discoverer in the top-level discovery
# # section (connection settings), a template backend (is_template: true), and
# # the ALB's alb.discovery block (what to select + guardrails).
#
# discovery: # top-level section of named discoverers; multiple ALBs can share one
#   in-cluster:
#     # valid providers: kubernetes, dns_srv, dns_a, file, http_sd, consul, nomad, 
      # aws, gcp, azure, docker -- see docs or below for configuring specific providers
#     provider: kubernetes 
#     kubernetes:
#       in_cluster: true # use the pod's service account (default)
#       # kubeconfig: /path/to/kubeconfig # or run against a remote cluster
#       qps: 20          # client-side sustained API request rate (default 20)
#       burst: 40        # client-side API request burst allowance (default 40)
#       timeout: 10s     # bounds one-shot API calls (e.g. the startup_policy:
#                        # fail preflight); watches are never truncated by it
#       # user_agent: my-trickster/1 # default: trickster/<version> (<os>/<arch>)
#   corp-dns:
#     provider: dns_srv
#     dns:
#       resolver: 10.0.0.53:53 # optional; default: the system resolver
#       interval: 30s          # poll cadence; record TTLs act as a floor
#   external-sd:
#     provider: file
#     file:
#       poll_interval: 30s # stat-poll fallback cadence (notification is primary)
#   remote-sd:
#     provider: http_sd # fetch the member list from an http endpoint
#     http:             # the shared outbound-client block for http providers
#       endpoint: https://sd.example.com
#       interval: 30s   # poll cadence
#       timeout: 10s    # bound on a single poll
#       # headers:      # sent on every request
#       #   X-Custom-Token: value
#       # bearer_token_file: /var/run/secrets/sd-token # re-read per poll, so
#       #                                              # rotation needs no restart
#       # tls:
#       #   certificate_authority_paths: [/etc/ssl/corp-ca.pem]
#     http_sd:
#       format: trickster # trickster (default) or prometheus (file_sd/http_sd json)
#   consul-dc1:
#     provider: consul # event-driven: blocking queries, not polling
#     http:
#       endpoint: http://127.0.0.1:8500
#       # bearer_token_file: /var/run/secrets/consul-token # rotated acl token
#       # timeout: defaults to consul.wait plus a margin; must exceed the wait
#     consul:
#       datacenter: dc1
#       wait: 5m           # how long a blocking query parks on the server
#       allow_stale: true  # answer from any server, not only the leader
#       # only_passing: false     # default: report failing instances as NotReady
#       # warning_is_ready: true  # default: warning instances still take traffic
#   nomad-eu:
#     provider: nomad # nomad's NATIVE registry; jobs registering into consul
#                     # should use the consul provider, which also conveys health
#     http:
#       endpoint: http://127.0.0.1:4646
#       # bearer_token_file: /var/run/secrets/nomad-token # rotated acl token
#     nomad:
#       namespace: default
#       region: eu-1
#       wait: 5m
#       allow_stale: true
#   ec2-fleet:
#     provider: aws
#     aws:
#       service: ec2      # REQUIRED: ec2 (instances) or ecs (tasks, incl.
#                         # fargate); also the sigv4 signing service
#       region: us-east-1 # the api endpoint is derived from this
#       # credentials omitted: use the standard chain (irsa, instance
#       # profile, environment, shared config). see docs/aws.md
#       # profile: production
#       # role_arn: arn:aws:iam::123456789012:role/TricksterDiscovery
#     http:
#       interval: 60s     # instance inventories change slowly
#   gcp-fleet:
#     provider: gcp
#     gcp:
#       service: gce # REQUIRED: the google cloud product to read
#       project: my-project # read from the metadata server when unset
#       # credentials_file: /etc/trickster/sa.json # must be a service
#       #   account key; omit to use application default credentials
#       #   (workload identity on gke, the instance service account on gce)
#     http:
#       interval: 60s
#   azure-fleet:
#     provider: azure
#     azure:
#       service: vm # REQUIRED: the azure api to read
#       subscription_id: 00000000-0000-0000-0000-000000000000 # REQUIRED
#       # resource_group: prod-rg # narrows every list; recommended on a
#       #   large subscription
#       # credentials omitted: use the managed identity of the azure vm or
#       #   aks pod. for aks workload identity set federated_token_file; for
#       #   a service principal set tenant_id + client_id + client_secret
#       # cloud: public # public (default), usgovernment, or china
#       # power_state: false # one extra list call; makes readiness real
#     http:
#       interval: 60s
#   containers:
#     provider: docker
#     docker: {} # api_version: v1.41 by default
#     http:
#       # endpoint: unix:///var/run/docker.sock # the default; tcp:// for a
#       #   remote daemon, whose tls goes in the shared tls block below
#       interval: 30s
#
# backends:
#   prom-template:
#     provider: prometheus
#     is_template: true # never routed; cloned per discovered member, which
#                       # inherits its cache, TLS, healthcheck, paths, etc.
#     cache_name: default
#     healthcheck:
#       interval: 5s
#
#   prom-alb:
#     provider: alb
#     alb:
#       mechanism: tsmerge
#       # pool: [ static-member ] # optional; discovered members are additive
#       discovery:
#         discoverer_name: in-cluster    # a name from the discovery section
#         template_backend: prom-template
#         query: # provider-specific selection; kubernetes shown
#           kind: endpointslices # endpointslices (default), service, or pods
#           namespace: monitoring
#           service: prometheus
#           port: web # port name or number; optional when the target has one port
#           # replica_group_label: prometheus/shard # per-member TSM replica groups
#         min_members: 1        # reject snapshots that would shrink below this
#         debounce_window: 5s   # damp flapping sources
#         startup_policy: retry # retry (default) or fail when the discoverer is unavailable
#         health_mode: probe    # probe (default) or provider (use discoverer readiness)

# # Configuration Options for Request Routing Rules - see /docs/rule.md for more information

# rules:
# # This example rule will route a request to the reader or writer backend based on the Username header

#   example:
#     input_source: header       # path, host, param
#     input_key: Authorization   # Authorization: Basic SomeBase64EncodedString
#     input_type: string
#     input_encoding: base64
#     input_index: 1               # split the header value into zero-indexed parts at spaces, use part 1
#     input_delimiter:  
#     operation: prefix              # check the input value matches any of the defined cases:
#     next_route: reader-cluster # by default, route to reader-cluster backend (would need to be defined)
# #  Other available rule configs that are not pertinent to this example:
#     ingress_req_rewriter_name: '' # name of a rewriter to process the request before evaluating the rule
#     egress_req_rewriter_name: ''  # name of a rewriter to process the request after evaluating the rule
#   #                                 # and handing off to the new route
#     nomatch_req_rewriter_name: '' # name of a rewriter to run the request through when there are no matching cases
#     operation_arg: '' # an argument to pass to the operation.
#     redirect_url: '' # provides a URL to redirect the request in the default case, rather than handing to next_route
#     max_rule_executions: 16        # limits the max number of per-Request rule-based hops to avoid execution loops.

#     cases:
#         - matches:     # if the Authorization header has user johndoe or janedoe
#           - 'johndoe:'
#           - 'janedoe:'  
#         next_route: writer-cluster       # route the request to hypothetical writer-cluster backend
#   #     Other available case configs that are not pertinent to this example:
#         req_rewriter_name: '' # name of a rewriter to process the request if it matches this case
#                               # case rewrites are executed prior to giving control back to the rule
#         redirect_url: ''  # provides a URL to redirect the request if it matches this case


# # Configuration Options for Request Rewriter Instructions - see /docs/request_rewriters.md for more info

# request_rewriters:
#   example-rewriter: # this example sets an authorization header before calling the origin
#     instructions: [
#       [header, set, Authorization, Basic SomeBase64EncodedCredentials],
#     ]

# # Configuration Options for Tracing Instrumentation. see /docs/tracing.md for more information
# tracing:

#     # This is the default tracing config with its default options, which you can change here.
#     # you can also add additional tracing configs here. user-defined tracing configs are mapped
#     # to backends by the tracing_name value in backend configs, which, by default, use default
#   default:

#     # provider specifies the type of backend tracing system where traces are sent (in that format)
#     # options are: otlp, stdout or none.  none is the default
#     provider: none

#     # protocol selects the OTLP transport. options are: http or grpc. http is the default
#     # protocol only applies when provider is otlp.
#     protocol: http

#     # service_name specifies the service name under which the traces are registered by this tracer
#     # default is trickster
#     service_name: trickster

#     # endpoint is the URL, URI or Path to the tracing backend
#     # required for OTLP, unused for stdout. For Jaeger OTLP/HTTP, use
#     # http://jaeger:4318/v1/traces. For Jaeger OTLP/gRPC, set protocol: grpc
#     # and use http://jaeger:4317 for a plaintext local collector.
#     endpoint: http://jaeger:4318/v1/traces

#     # timeout is the amount of time in arbitrary time units (ns, ms, s, h, d) for the tracing post
#     # to wait for a response before timing out
#     # default is no timeout set
#     timeout: 5s

#     # headers is a list of http headers to include in the tracing post
#     # default is none
#     headers:
#       "Header-Name-1": "header value 1"
#       "Header-Name-2": "header value 2"

#     # disable_compression should be set to true if tracing posts should not be compressed
#     # default is false
#     disable_compression: false

#     # sample_rate sets the probability that a root trace started by Trickster will be recorded.
#     # when a request already has remote trace context, Trickster follows the parent's sampling decision.
#     # A floating point value of 0.0 to 1.0 (inclusive) is permitted
#     # default is 1.0 (meaning 100% of requests are recorded)
#     sample_rate: 1.0

#     # omit_tags is a list of tag names that, while normally added by Trickster to various spans,
#     # are omitted for spans produced by this tracer. The default setting is empty list.
#     omit_tags: []
    
#       # tags will append these tags/attributes to each trace that is recorded
#       # only string key/value tags are supported. numeric values, etc are not.
#       # default tags list is empty
#     tags:
#       key1: "value1"
#       key2: "value2"

#       # configurations for this tracer, specific to stdout
#     stdout:
#       # pretty_print indicates whether the output to stdout is formatted better human readability
#       # default is false
#       pretty_print: false

#     # another example tracing config named example using OTLP/HTTP and a 50% sample rate
#   example:
#     provider: otlp
#     protocol: http
#     endpoint: http://jaeger:4318/v1/traces
#     sample_rate: 0.5

#     # another example tracing config named example-grpc using OTLP/gRPC
#   example-grpc:
#     provider: otlp
#     protocol: grpc
#     endpoint: http://jaeger:4317
#     sample_rate: 0.5

# # Configuration Options for Authentication
# authenticators:
#   example_auth_1:
#     # provider (required) is the type of Authenticator. Currently supported: basic (basic auth), clickhouse
#     provider: basic
#     # proxy_preserve, when true, will pass the Authentication headers through on proxied requests.
#     # The default value (false) will cause Authentication headers to be stripped from proxied requests
#     # when an inbound request is permitted by this Authenticator.
#     proxy_preserve: false
#     # users_file is the optional users source file
#     users_file: /path/to/user-manifest.csv
#     # users_file_format is the source file format. Required when users_file is set. Valid options: csv, csvNoHeader, htpasswd
#     users_file_format: csv
#     # users is an optional embedded users list (format is: name: credential)
#     users: 
#       user1: red123
#     # config holds optional provider-specific configs
#     config:
#       # basic auth optional configs:
#       # showLoginForm (default: false) will cause the user's browser to show the Basic Auth Login modal when
#       # required credentials are not provided or are invalid
#       showLoginForm: true 
#       # realm is the realm valid shown to on the Basic Auth Login modal. If not set, the realm will default
#       # to the authenticator name (e.g., example_auth_1)
#       realm: custom-realm-name

# # Geo Locators place a client address. A geo ACL uses the locator named default unless it names another, so
# # several geo ACLs can share one database. See /docs/geo-acl.md
# geo_locators:
#   default:
#     # provider (required) is how the locator places clients: mmdb, geofeed or header
#     provider: mmdb
#     # the mmdb provider reads a MaxMind DB format file: MaxMind GeoIP2 and GeoLite2, DB-IP, IPinfo, or an
#     # IP2Location MMDB edition. Trickster ships no database; mount one, and keep it updated, yourself
#     mmdb:
#       # path (required) is the database file. a Country file places countries and continents; a City
#       # file adds first-level subdivisions
#       path: /var/lib/GeoIP/GeoLite2-Country.mmdb
#       # schema says where the file's records keep the location fields: auto (default) chooses from the
#       # file's database_type; geoip2 is MaxMind's layout, which DB-IP and IP2Location follow; ipinfo is
#       # IPinfo's; custom takes the paths in fields
#       schema: auto
#       # fields are the record paths of each location field when schema is custom. country is required
#       # fields:
#       #   country: [country, iso_code]
#       #   continent: [continent, code]
#       #   subdivision: [subdivisions, 0, iso_code]
#       # reload_interval is how often the file is checked for a replacement, besides change events. A
#       # replacement is swapped in while serving; one that fails to load leaves the last good file in place.
#       # 10s to 24h; default is 5m
#       reload_interval: 5m
#       # max_age logs a warning while the loaded file was built longer ago than this. default is 0 (never)
#       max_age: 0s

#   city:
#     provider: mmdb
#     mmdb:
#       path: /var/lib/GeoIP/GeoLite2-City.mmdb

#   corrections:
#     provider: geofeed
#     # the geofeed provider places addresses by RFC 8805 lines: prefix,country,region,city,postal code.
#     # city and postal code are ignored; a line with no location places no one
#     geofeed:
#       # entries are inline lines; one beats a file's line for the same prefix
#       entries:
#         - 203.0.113.0/24,DE,DE-BE
#         - 2001:db8::/32,US,US-CA
#       # files are geofeed files, watched and swapped in as mmdb files are. Write a new file and rename it
#       # over the old one; a replacement that loses every entry is refused
#       files: [ /etc/trickster/private-relay.csv ]
#       # reload_interval is as above. default is 5m
#       reload_interval: 5m

#   edge:
#     provider: header
#     # the header provider reads a location header that a CDN or load balancer in front of Trickster set. It
#     # believes the header only from the listener's trusted_proxies, and judges HTTP requests only
#     header:
#       # country (required) is the header holding a country code
#       country: CF-IPCountry
#       # subdivision optionally names a header holding a subdivision code, such as CloudFront-Viewer-Country-Region
#       subdivision: ''
#       # continent optionally names a header holding a continent code
#       continent: ''
#       # unknown_values are header values that mean no location. default is [XX, T1, ZZ, '-']
#       unknown_values: [ XX, T1, ZZ, '-' ]

# # Geo ACLs restrict backends and paths, which name them with geo_acl_name, by where their clients are.
# # HTTP refusals are a 403 by default; native protocol listeners refuse a session in their own error form,
# # and tcp, tls and udp listeners reset or drop it. See /docs/geo-acl.md
# geo_acls:
#   north-america:
#     # geo_locator_name names the locator that places clients. default is default
#     geo_locator_name: default
#     # allow lists the only locations allowed, and deny the locations denied; set one, never both. An entry is a
#     # country (US), a first-level subdivision (US-TX), or a continent (continent:EU)
#     allow: [ US, CA, MX ]
#     # unknown judges a client the locator cannot place: allow or deny. default is as an unlisted location,
#     # which is deny for an allow list and allow for a deny list
#     unknown: deny
#     # exempt lists addresses and prefixes allowed without a lookup; private stands for every non-routable range
#     exempt: [ private, 198.51.100.0/24 ]
#     # action is what a denial does: reject (default), or count, which counts it, allows the client and names
#     # the geo ACL in an X-Trickster-Geo-Denied request header to the origin
#     action: reject
#     # message is what a refused client is told, in every protocol. it is one line of at most 255 bytes
#     message: This resource is not available in your geographical area.
#     # response shapes the HTTP refusal
#     response:
#       # status is from 400 to 599. default is 403; 451 is for a legal demand, and wants a Link header with
#       # rel="blocked-by"
#       status: 403
#       # headers are merged over the default Cache-Control: no-store and Content-Type: text/plain; charset=utf-8
#       headers:
#         Cache-Control: no-store
#       # body replaces the message and a newline as the body
#       body: "This resource is not available in your geographical area.\n"

#   europe:
#     allow: [ continent:EU ]

#   no-restricted-states:
#     # first-level subdivisions need a locator that serves them, such as an mmdb City file
#     geo_locator_name: city
#     deny: [ US-TX, US-UT ]

# # A complete native MySQL User Router example, including its listener,
# # authenticator, two direct terminal origins, isolated caches, and default
# # routing policy, is provided in examples/conf/mysql-user-router.yaml.
# # Native MySQL routing does not support to_user or to_credential remapping.

# # access_log at the top level is the default access and error log for every backend that does not
# # define its own access_log block, and it also logs requests that no backend route handled (404s and
# # the built-in ping, readiness, health and management endpoints, attributed to backend '-'). It accepts
# # every option shown in the per-backend access_log block above. A backend's own access_log block
# # replaces this default entirely; an empty block disables logging for that backend.
# access_log:
#   # filename and error_filename accept a file path or the streams stdout / stderr, which are never
#   # rotated and ignore rotation, retention, compress and instance_id
#   filename: stdout
#   format: json

# # acme obtains and renews serving certificates from an ACME certificate authority for backends
# # that set tls.acme. See /docs/acme.md
# acme:
#   # wait_on_startup holds readiness at startup until missing certificates are issued, or this long
#   # at most. default is 0, which never holds readiness
#   wait_on_startup: 90s
#   storage:
#     # provider is filesystem, redis or valkey; default is filesystem
#     provider: filesystem
#     # path is the storage directory, required for filesystem storage
#     path: /var/lib/trickster/acme
#     # redis keeps ACME state in Redis, shared by every instance using the same keyspace
#     # redis:
#     #   cache_name: shared-redis      # borrow a redis cache's connection settings, or set connection
#     #   key_prefix: "trickster:acme:"
#     #   lock_ttl: 1m
#     # valkey keeps ACME state in Valkey the same way, and its locks work on a server without Lua
#     # valkey:
#     #   cache_name: shared-valkey     # borrow a valkey cache's connection settings, or set connection
#     #   key_prefix: "trickster:acme:"
#     #   lock_ttl: 1m
#   issuers:
#     letsencrypt:
#       # directory_url defaults to the Let's Encrypt production directory
#       directory_url: https://acme-v02.api.letsencrypt.org/directory
#       email: ops@example.com
#       # agree_to_terms accepts the CA's subscriber agreement and must be true
#       agree_to_terms: true
#       # challenges defaults to [http-01, tls-alpn-01], or [dns-01] when dns_provider is set
#       challenges: [http-01, tls-alpn-01]
#       # key_type is ecdsa-p256 (default), ecdsa-p384, rsa-2048, rsa-4096 or ed25519
#       key_type: ecdsa-p256
#       # external_account_binding:
#       #   key_id: your-key-id
#       #   hmac_key_file: /etc/trickster/secrets/eab-hmac
#       # trusted_ca_paths: [ /etc/trickster/private-ca.pem ]
#     letsencrypt-dns:
#       email: ops@example.com
#       agree_to_terms: true
#       # dns_provider answers dns-01 challenges, which wildcard certificates require
#       dns_provider:
#         provider: cloudflare        # cloudflare, route53 or rfc2136
#         cloudflare:
#           api_token_file: /etc/trickster/secrets/cloudflare-token
#   # on_demand issues a certificate during the first handshake for a permitted name no backend lists
#   # on_demand:
#   #   issuer: letsencrypt
#   #   listeners: [default]
#   #   ask: http://127.0.0.1:9000/allowed     # GET ?domain=<name>; a 200 permits issuance
#   #   allowed_domains: ["*.customers.example.com"]
#   #   decision_ttl: 5m
#   #   rate_limit: 10

# # Trickster Management Options
# mgmt:
#   # reload_handler_path defines the HTTP path where the Reload interface is available.
#   # by default, this is /trickster/config/reload
#   reload_handler_path: /trickster/config/reload
#   # reload_drain_timeout defines how long old HTTP listeners will live to allow
#   # outstanding connection to close organically, before the listener is forcefully closed
#   # during a configuration reload
#   # the default is 30s
#   reload_drain_timeout: 30s
#   # reload_rate_limit specifies the rate limit timeout duration to apply to operator-requested
#   # reloads (SIGHUP and the HTTP reload interface). Those are ignored for this duration after any
#   # reload check. Automatic and in-process reloads are not rate limited. default is 3s
#   reload_rate_limit: 3s
#   # auto_reload_interval controls how often Trickster checks the effective configuration sources for changes.
#   # A zero value disables automatic reloads. default is 0s
#   auto_reload_interval: 10s
#   # shutdown_delay keeps listeners accepting connections for this long after SIGTERM/SIGINT while the
#   # readiness handler already reports 503, so load balancers can stop routing here first. default is 0s
#   shutdown_delay: 5s
#   # shutdown_drain_timeout bounds how long in-flight requests may run after the shutdown delay before
#   # their connections are closed. A second SIGTERM/SIGINT closes them immediately.
#   # the default is the value of reload_drain_timeout
#   shutdown_drain_timeout: 30s

#   # ready_handler_path provides the HTTP path of the readiness handler, which returns 200 only while
#   # every listener is serving and no shutdown is in progress. It is served on every proxy listener and
#   # on the management listener. default is /trickster/ready
#   ready_handler_path: /trickster/ready

#   # config_handler_path provides the HTTP path to view a read-only printout of the running configuration
#   # which can be reached at http://your-trickster-endpoint:port/$config_handler_path
#   # default is /trickster/config
#   config_handler_path: /trickster/config

#   # config_handler_listener provides the HTTP listener that hosts the config endpoints
#   # Options are: "metrics", "mgmt", "both", or "off"; default is mgmt
#   config_handler_listener: mgmt

#   # certificates_handler_path provides the HTTP path to view a read-only JSON inventory
#   # of the TLS certificates served by each listener (metadata only; never key material)
#   # default is /trickster/certificates
#   certificates_handler_path: /trickster/certificates

#   # acme_handler_path provides the mgmt-only HTTP path that lists ACME-managed domains (GET)
#   # and forces a renewal (POST ?domain=<name>). default is /trickster/acme
#   acme_handler_path: /trickster/acme

#   # ping_handler_path provides the HTTP path you will use to perform an uptime health check against Trickster
#   # which can be reached at http://your-trickster-endpoint:port/$ping_handler_path
#   # default is /trickster/ping
#   ping_handler_path: /trickster/ping

#   # health_handler_path provides the HTTP path prefix you will use to perform an uptime health check against
#   # configured Trickster backends via http://trickster/$health_handler_path/$backend_name
#   # default is /trickster/health. Set to empty string to fully disable upstream health checking
#   health_handler_path: /trickster/health

#   # pprof_listener provides the name of the http listener that will host the pprof debugging routes
#   # Options are: "metrics", "mgmt", "both", or "off"; default is both
#   pprof_listener: both

# # Configuration Options for Logging Instrumentation
# logging:
#   # log_level defines the verbosity of the logger. Possible values are debug, info, warn, error
#   # default is info
#   log_level: info

#   # log_file defines the file location to store logs. These will be auto-rolled and maintained for you.
#   # not specifying a log_file (this is the default behavior) will print logs to STDOUT
#   log_file: /some/path/to/trickster.log

#   # rotation controls when the log file is rotated; a rotation occurs when either threshold is reached.
#   # rotated archives are kept alongside the live file as trickster.log.1.gz, .2.gz, etc.
#   rotation:
#     # size rotates the log when the live file would exceed this size. default is 256MB
#     size: 256MB
#     # interval rotates the log when the live file is older than this. default is 0 (off)
#     interval: 1d

#   # retention controls how many rotated archives are kept
#   retention:
#     # count is the maximum archives kept; 0 is unlimited. default is 80
#     count: 80
#     # age prunes archives older than this. default is 7d
#     age: 7d

#   # compress gzips rotated archives. default is true
#   compress: true

#   # redact masks credentials in access logs and engine logs. It is on by default and
#   # always covers the built-in names listed in /docs/access-logs.md; the lists add names.
#   redact:
#     # enabled: false turns redaction off entirely. default is true
#     enabled: true
#     # query_params are query parameter names whose values are masked, matched without case
#     query_params: [session_id]
#     # headers are request or response header names whose values are masked
#     headers: [X-Internal-Token]
#     # cookies are the cookie names whose values %{name}c masks. none by default
#     cookies: [grafana_session]

# # Kubernetes Gateway API / Ingress controller - see /docs/configuring.md and
# # /docs/kubernetes-rbac.md for more information.
# #
# # The controller does not exist unless this section is present: a Trickster
# # that is not a Kubernetes gateway holds no watches and generates no config.
# kubernetes:
#   # enabled defaults to true when the section is present; set false to keep
#   # the configuration in place while shutting the controller off
#   enabled: true
#
#   # connection is the Kubernetes API connection; same options as a
#   # discovery entry's 'kubernetes' block
#   connection:
#     in_cluster: true # use the pod's service account (default)
#     # kubeconfig: /path/to/kubeconfig # or run against a remote cluster
#     qps: 20          # client-side sustained API request rate
#     burst: 40        # client-side API request burst allowance
#     timeout: 10s     # bounds one-shot API calls; never truncates watches
#     # user_agent: my-trickster/1 # default: trickster/<version> (<os>/<arch>)
#
#   # the controllerName this instance claims GatewayClasses with, and which
#   # is matched against an IngressClass's spec.controller. Objects naming
#   # any other controller are ignored and never statused.
#   gateway_class_controller_name: trickstercache.org/gateway-controller
#
#   # ingress_class narrows ownership to the IngressClass of that name, so two
#   # instances can split one cluster. Empty claims every IngressClass naming
#   # this controller.
#   ingress_class: trickster
#
#   # watch_namespaces narrows the watches themselves, so a namespace-scoped
#   # RBAC grant suffices. Empty watches every namespace.
#   watch_namespaces:
#     - team-a
#     - team-b
#
#   # namespace_selector watches all namespaces and filters by namespace
#   # labels; it additionally needs cluster-wide namespace read access.
#   # Mutually exclusive with watch_namespaces.
#   # namespace_selector:
#   #   trickstercache.org/gateway: enabled
#
#   # resync_interval is the informer resync period: a backstop for missed
#   # watch events, not the primary update path
#   resync_interval: 10m
#
#   # debounce_window coalesces a burst of watch events into one translation
#   # pass, so a rollout touching many objects yields one reload
#   debounce_window: 1s
#
#   # read_only stops this instance writing to the Kubernetes API at all: no
#   # status on the objects it claims, no Events, and no leader election
#   # Lease, since the election only decides which replica does the writing.
#   # It still watches, translates and serves traffic; read-only describes
#   # the relationship with the cluster, not the data plane. default is false
#   read_only: false
#
#   # leader_election decides which replica writes status and Events. Every
#   # replica programs its own data plane regardless, so losing an election
#   # never stops a replica serving.
#   leader_election:
#     enabled: true # default true: two replicas writing one object conflict
#     # namespace: trickster # default: the pod's own namespace
#     name: trickster-gateway-controller
#     lease_duration: 15s # at least 1s; the Lease API stores whole seconds
#     renew_deadline: 10s # must be less than lease_duration
#     retry_period: 2s    # must be less than renew_deadline / 1.2
#
#   # ingress serves claimed Ingress v1 objects. An Ingress cannot describe
#   # the ports it is served on, so unlike the Gateway API it names the
#   # listeners it is served on, exactly as a backend does. Their ports,
#   # bind addresses, body limits and TLS settings are configured in the
#   # 'listeners' section like any other listener's. Naming none serves
#   # claimed Ingresses on the default frontend.
#   #
#   # A listener that serves TLS needs 'tls_runtime_certs: true', because
#   # the certificates arrive at runtime from the Secrets the claimed
#   # Ingresses reference rather than from files.
#   ingress:
#     listener_names:
#       - web
#       - websecure
#
#   # published_service names the Service whose addresses are published into
#   # Gateway and Ingress status. Without it, no address is published.
#   published_service:
#     namespace: trickster
#     name: trickster-gateway
#
#   # defaults shapes the backends the controller generates
#   defaults:
#     # routing_mode is REQUIRED and has no default. 'service' sends traffic
#     # to the Service cluster IP and lets kube-proxy load balance;
#     # 'endpoint' discovers the Service's endpoints and load balances across
#     # them in-process. The two have different failure modes, so Trickster
#     # refuses to guess.
#     routing_mode: service
#     cache_name: default # the cache generated caching backends use
#     # the negative cache generated caching backends use; a route may name
#     # a different one with trickstercache.org/negative-cache-name
#     negative_cache_name: default
#     # the settings below name objects configured elsewhere in this file and
#     # have no annotation: selecting a tracer is infrastructure, and an
#     # annotation that can name an authenticator can also omit it
#     tracing_name: otlp
#     req_rewriter_name: strip-internal-headers
#     authenticator_name: gateway-auth
#     timeout: 180s       # upstream timeout for generated backends
#     # health_mode of generated discovery-backed ALBs: 'provider' (default)
#     # or 'probe'. EndpointSlice readiness already answers the question
#     # active probes would ask.
#     health_mode: provider
#     # healthcheck is the active probe the discovered members of a generated
#     # ALB run when health_mode is 'probe'; same options as a backend's
#     # healthcheck block. Unset probes the origin root every 5s. It is not
#     # read in the 'provider' health mode.
#     # healthcheck:
#     #   path: /healthz
#     #   interval: 5s
#     # access_log generated backends inherit; unset inherits the top-level
#     # access_log block
#     # access_log:
#     #   filename: stdout
#     #   format: combined
#     # sticky_secret_file keys the session tokens generated ALBs issue for a
#     # route's sessionPersistence or a sticky annotation, parameter or policy:
#     # at least 32 bytes, mounted from a Secret at the same path on every
#     # replica. Unset, each process uses its own random key (one replica only).
#     # sticky_secret_file: /etc/trickster/sticky/key