### Install and Run Trickster from Source

Source: https://context7.com/trickstercache/trickster/llms.txt

Install Trickster using 'go install' and run it as a single-origin Prometheus accelerator. Ensure Go 1.26+ is installed.

```bash
go install github.com/trickstercache/trickster/cmd/trickster@main
trickster -origin-url http://prometheus.example.com:9090 -provider prometheus
```

--------------------------------

### Install Trickster Binary using Go

Source: https://github.com/trickstercache/trickster/blob/main/README.md

Installs the Trickster binary using the Go toolchain. Requires Go version 1.26 or greater.

```bash
$ go install github.com/trickstercache/trickster/cmd/trickster@main
# this starts a prometheus accelerator proxy for the provided endpoint
$ trickster -origin-url http://prometheus.example.com:9090 -provider prometheus
```

--------------------------------

### Start Docker Compose Demo

Source: https://github.com/trickstercache/trickster/blob/main/examples/docker-compose/README.md

Initializes the multi-service environment in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Request Rewriter Configuration Example

Source: https://github.com/trickstercache/trickster/blob/main/docs/request_rewriters.md

This example demonstrates how to define a Request Rewriter named 'example_rewriter' with a set of instructions, including chaining another rewriter.

```APIDOC
## Request Rewriter Configuration

Request Rewriters are defined as a map of named instruction sets.

### Example Configuration

```yaml
request_rewriters:
  example_rewriter:
    instructions:
      - [ 'header', 'set', 'Cache-Control', 'max-age=60' ]
      - [ 'path', 'replace', '/cgi-bin/', '/' ]
      - [ 'chain', 'exec', 'remove_accept_encoding' ]

  remove_accept_encoding:
    instructions:
      - [ 'header', 'delete', 'Accept-Encoding' ]
```

### Usage

Named rewriters can be referenced in other configuration constructs like `backend`, `path`, and `rule` using their respective configuration keys (e.g., `req_rewriter_name`).
```

--------------------------------

### Start Developer Environment and Seed Data

Source: https://github.com/trickstercache/trickster/blob/main/integration/README.md

Run this command from the repository root to start the Docker Compose environment and seed it with necessary data for integration tests.

```sh
make developer-start developer-seed-data
```

--------------------------------

### Example output of the release tag process

Source: https://github.com/trickstercache/trickster/blob/main/docs/developer/spinning-new-release.md

This shows the interactive prompt and the resulting git commands executed by the Makefile.

```bash
% TAG_VERSION=v1.2.345 make create-tag
FYI: the last proper tag was: v0.0.9
FYI: the last beta tag was: v2.0.0-beta2
Create tag v1.2.345? [y/N] y
git tag v1.2.345
git push origin v1.2.345
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:crandles/trickster.git
 * [new tag]           v1.2.345 -> v1.2.345
```

--------------------------------

### Bootstrap Local Kubernetes Environment

Source: https://github.com/trickstercache/trickster/blob/main/deploy/README.md

Commands to install tools for a standard Kubernetes development environment.

```bash
brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/e4b03ca8689987364852d645207be16a1ec1b349/Formula/kubernetes-cli.rb
brew pin kubernetes-cli
```

```bash
brew cask install https://raw.githubusercontent.com/caskroom/homebrew-cask/903f1507e1aeea7fc826c6520a8403b4076ed6f4/Casks/minikube.rb
```

--------------------------------

### Bootstrap Local Kubernetes-Helm Environment

Source: https://github.com/trickstercache/trickster/blob/main/deploy/README.md

Commands to install necessary tools for a Helm-based Kubernetes development environment.

```bash
brew install kubernetes-helm
```

```bash
curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.13.4/bin/darwin/amd64/kubectl && chmod +x kubectl && sudo mv kubectl /usr/local/bin/
```

```bash
curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.23.2/minikube-darwin-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/
```

--------------------------------

### Define Multiple Backends in YAML

Source: https://github.com/trickstercache/trickster/blob/main/docs/multi-origin.md

Example configuration demonstrating how to define multiple backends with different routing strategies including path-based and host-based routing.

```yaml
backends:
  my-backend-01: # routed via http://trickster:8480/my-backend-01/
    provider: prometheus
    origin_url: http://my-origin-01.example.com

  my-backend-02: # routed via http://trickster:8480/my-backend-02/
    hosts: [ my-fqdn-02.example.com ] # or http://my-fqdn-02.example.com:8480/
    provider: prometheus
    origin_url: http://my-origin-02.example.com

  my-backend-03:
    path_routing_disabled: true # only routable via Host header, an ALB, or a Rule
    hosts: [ my-fqdn-03.example.com ] # or http://my-fqdn-03.example.com:8480/
    provider: prometheus
    origin_url: http://my-origin-02.example.com
```

--------------------------------

### Trickster Prometheus Accelerator Usage Examples

Source: https://context7.com/trickstercache/trickster/llms.txt

Examples of cURL commands to interact with Trickster when configured as a Prometheus accelerator. Demonstrates range queries, instant queries, series metadata, and label fetching.

```bash
# Grafana / client sends a range query — Trickster serves only the missing delta
curl "http://trickster:9090/api/v1/query_range?query=up&start=1609459200&end=1609462800&step=60"

# Instant query — Object Proxy Cache
curl "http://trickster:9090/api/v1/query?query=up&time=1609459200"

# Series metadata — Object Proxy Cache + Scatter/Gather merge with ALB
curl "http://trickster:9090/api/v1/series?match[]=up&start=1609459200&end=1609462800"

# Labels — cached
curl "http://trickster:9090/api/v1/labels"

# Admin endpoints — explicitly blocked by Trickster (returns error)
curl "http://trickster:9090/api/v1/admin/tsdb/delete_series"
# => error: admin endpoints are not supported

# Prometheus 3.x query with stats
curl "http://trickster:9090/api/v1/query_range?query=up&start=...&end=...&step=60&stats=all"
# stats=all is part of the cache key, so stats and non-stats responses are cached separately

```

--------------------------------

### Simulated Latency Response Header Example

Source: https://github.com/trickstercache/trickster/blob/main/docs/simulated-latency.md

This example shows the 'x-simulated-latency' header in a response, indicating the duration of applied latency in milliseconds.

```bash
GET /api/v1/query?query=up HTTP/1.1
Accept: */*
...

HTTP/1.1 200 OK
X-Simulated-Latency: 300ms
X-Trickster-Result: engine=DeltaProxyCache; status=hit; ffstatus=hit
Date: Mon, 06 Sep 2021 04:07:20 GMT
...
```

--------------------------------

### Run Trickster with Docker

Source: https://github.com/trickstercache/trickster/blob/main/deploy/README.md

Starts a Trickster container with an optional volume mount for configuration.

```bash
$ docker run --name trickster -d [-v /path/to/trickster.yaml:/etc/trickster/trickster.yaml] -p 0.0.0.0:9090:9090 trickstercache/trickster:latest
```

--------------------------------

### Configure Path-based Routing

Source: https://github.com/trickstercache/trickster/blob/main/docs/multi-origin.md

Example configuration for routing multiple backends using a single FQDN with path-based indicators.

```yaml
backends:
  # backend1 backend
  backend1:
    origin_url: 'http://prometheus.example.com:9090'
    provider: prometheus
    cache_name: default
    is_default: true
  # "foo" backend
  foo:
    origin_url: 'http://influxdb-foo.example.com:9090'
    provider: influxdb
    cache_name: default
  # "bar" backend
  bar:
    origin_url: 'http://prometheus-bar.example.com:9090'
    provider: prometheus
    cache_name: default
```

--------------------------------

### Example Round Robin ALB Configuration

Source: https://github.com/trickstercache/trickster/blob/main/docs/alb.md

Configures an ALB named 'node-alb' to distribute requests in a round-robin fashion across 'node01' and 'node02' backends. This example demonstrates how to define traditional Trickster backends and then group them under an ALB provider.

```yaml
backends:

  # traditional Trickster backend configurations

  node01:
    provider: reverseproxycache # will cache responses to the default memory cache
    path_routing_disabled: true # disables frontend request routing via /node01 path
    origin_url: https://node01.example.com # make requests with TLS
    tls: # this backend might use mutual TLS Auth
      client_cert_path: ./cert.pem
      client_key_path: ./cert.key

  node02:
    provider: reverseproxy      # requests will be proxy-only with no caching
    path_routing_disabled: true # disables frontend request routing via /node02 path
    origin_url: http://node-02.example.com # make unsecured requests
    request_headers: # this backend might use basic auth headers
      Authoriziation: "basic jdoe:${NODE_02_AUTH_TOKEN}"

  # Trickster 2.0 ALB backend configuration, using above backends as pool members

  node-alb:
    provider: alb
    alb:
      mechanism: rr # round robin
      pool:
        - node01 # as named above
        - node02
        # - node02 # if this node were uncommented, weighting would change to 33/67
        # add backends multiple times to establish a weighting protocol.
        # when weighting, use a cycling list, rather than a sorted list.
```

--------------------------------

### Querying InfluxDB via Trickster

Source: https://context7.com/trickstercache/trickster/llms.txt

Examples of querying InfluxDB 1.x (InfluxQL) and 2.x (Flux) through Trickster. InfluxQL uses GET requests, while Flux uses POST. The /ping endpoint is proxied transparently.

```bash
# InfluxQL range query via GET (accelerated)
curl "http://trickster:8480/query?db=mydb&q=SELECT+mean(value)+FROM+cpu+WHERE+time +%3E%3D +'2021-01-01T00%3A00%3A00Z'+AND+time +%3C+'2021-01-01T01%3A00%3A00Z'+GROUP+BY+time(60s)"
```

```bash
# Flux query via POST (basic usage accelerated; complex union-style queries are proxied only)
curl -X POST "http://trickster:8480/api/v2/query" \
  -H "Content-Type: application/vnd.flux" \
  --data 'from(bucket:"myBucket") |> range(start: -1h) |> filter(fn:(r) => r._measurement == "cpu")'
```

```bash
# Health check — proxied transparently
curl "http://trickster:8480/ping"
# => 204 No Content (InfluxDB compatible)
```

--------------------------------

### Start Trickster Harness

Source: https://github.com/trickstercache/trickster/blob/main/integration/README.md

Boot a Trickster instance using the tricksterHarness helper. This method allows specifying a custom configuration path and base/metrics addresses. It's used when custom backends like ALB pools or rule routing are needed.

```go
tricksterHarness{ConfigPath, BaseAddr, MetricsAddr}.start(t)
```

--------------------------------

### Trickster Prometheus Accelerator Configuration

Source: https://context7.com/trickstercache/trickster/llms.txt

Example configuration for Trickster as a Prometheus accelerator. This setup allows Grafana to point to Trickster instead of Prometheus directly, leveraging caching for performance.

```yaml
# trickster.yaml — Prometheus accelerator configuration
frontend:
  listen_port: 9090   # Grafana points to this port instead of Prometheus directly

backends:
  default:
    provider: prometheus
    origin_url: http://prometheus:9090
    prometheus:
      labels:
        env: production   # inject into every response for federation use cases
    # Shard large range queries across concurrent upstream calls
    shard_max_size_points: 10999   # max data points per upstream shard
    # shard_max_size_time: 2h      # alternatively: max time range width per shard
    # shard_step: 2h               # epoch-aligned shard boundaries

```

--------------------------------

### HTTP Reverse Proxy Cache Usage

Source: https://context7.com/trickstercache/trickster/llms.txt

Examples of making requests to a Trickster HTTP reverse proxy cache. The first example shows a request to the /api/ path, where the cache key is derived from method, path, and Authorization header. The second example demonstrates checking the cache status via response headers.

```bash
# Request is proxied; cache key derived from method + path + Authorization header by default
curl http://trickster:8480/api/?query=hello
```

```bash
# Cache status reported in response header
curl -I http://trickster:8480/images/logo.png
# X-Trickster-Result: hit   (or: kmiss, rmiss, phit, nchit, rhit, proxy-only, proxy-error)
```

--------------------------------

### Configure and Use bbolt Cache in Go

Source: https://context7.com/trickstercache/trickster/llms.txt

This example shows how to configure and use the bbolt cache provider within a Go application. Ensure the bbolt package is imported and options are correctly set for filename and bucket.

```go
package main

import (
    "fmt"
    "time"

    // bbolt cache example (see examples/packages/cache/bbolt/main.go)
    bo "github.com/trickstercache/trickster/v2/pkg/cache/bbolt/options"
    "github.com/trickstercache/trickster/v2/pkg/cache/bbolt"
    co "github.com/trickstercache/trickster/v2/pkg/cache/options"
)

func main() {
    // Configure a bbolt cache
    opts := &co.Options{
        Provider: "bbolt",
        BBolt: &bo.Options{
            Filename: "/tmp/my-cache.db",
            Bucket:   "myapp",
        },
    }

    c, err := bbolt.NewCache("myapp", opts)
    if err != nil {
        panic(err)
    }
    defer c.Close()

    // Store an object with a 60-second TTL
    if err := c.Store("mykey", []byte("myvalue"), 60*time.Second); err != nil {
        panic(err)
    }

    // Retrieve the object
    val, _, err := c.Retrieve("mykey", false)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(val)) // => myvalue
}
```

--------------------------------

### Full Trickster Configuration with Chunking

Source: https://github.com/trickstercache/trickster/blob/main/docs/chunked_caching.md

A complete configuration example for a Prometheus backend using a memory cache with chunking enabled.

```yaml
frontend:
  listen_port: 8480

caches:
  mem1:
    provider: memory
    index:
      max_size_objects: 512
      max_size_backoff_objects: 128
    use_cache_chunking: true
    timeseries_chunk_factor: 380

backends:
  prom1:
    latency_max: 150ms
    latency_min: 50ms
    provider: prometheus
    origin_url: 'http://127.0.0.1:9090'
    cache_name: mem1

logging:
  log_level: warn

metrics:
  listen_port: 8481
```

--------------------------------

### Trickster Full Annotated Configuration

Source: https://context7.com/trickstercache/trickster/llms.txt

This is a comprehensive example of the trickster.yaml configuration file, illustrating various settings for frontend, caches, negative caches, backends, metrics, and logging.

```yaml
frontend:
  listen_port: 8480          # HTTP proxy listener
  tls_listen_port: 8483      # TLS proxy listener (requires cert/key on at least one backend)
  connections_limit: 0       # 0 = unlimited concurrent connections
  max_request_body_size_bytes: 10485760  # 10 MB default; -1 for no limit

caches:
  default:
    provider: memory         # options: memory, filesystem, bbolt, badger, redis
    memory:
      max_size_bytes: 536870912   # 512 MB hard admission limit
      num_counters: 500000
    # filesystem:
    #   cache_path: /tmp/trickster
    # redis:
    #   client_type: standard     # standard | cluster | sentinel
    #   endpoint: redis:6379
    #   password: "${MY_REDIS_PW}" # env-var substitution supported
    index:
      max_size_bytes: 536870912   # soft eviction threshold
      reap_interval: 3s
      flush_interval: 5s

negative_caches:
  default:
    "404": 3s   # cache 404 for 3s to prevent thundering-herd on missing objects
    "500": 5s
    "502": 5s

backends:
  default:
    provider: prometheus          # prometheus | influxdb | clickhouse | reverseproxycache | reverseproxy | alb | rule | rpc
    origin_url: http://prometheus:9090
    cache_name: default           # references a named cache config above
    negative_cache_name: default
    req_rewriter_name: ''         # optional named request rewriter
    tls:
      full_chain_cert_path: /path/to/cert.pem
      private_key_path: /path/to/key.pem
      insecure_skip_verify: false
      certificate_authority_paths: []
      client_cert_path: ''
      client_key_path: ''
    healthcheck:
      path: /-/healthy
      verb: GET
      timeout: 1000ms
      interval: 5000ms          # enables automated polling for ALB health reporting
      failure_threshold: 3
      recovery_threshold: 3
      expected_codes: [200, 204]
    prometheus:
      labels:
        datacenter: us-east-1   # labels injected into every Prometheus response

metrics:
  listen_port: 8481             # Prometheus /metrics endpoint

logging:
  log_level: info               # debug | info | warn | error

# Config reload endpoint: GET http://127.0.0.1:8484/trickster/config/reload
# View running config:    GET http://127.0.0.1:8484/trickster/config

```

--------------------------------

### Run All Trickster Load Tests

Source: https://github.com/trickstercache/trickster/blob/main/hack/load-test/README.md

Execute all available k6 test scripts for Trickster. Ensure k6 is installed and Trickster is running.

```sh
make run
```

--------------------------------

### Define Request Rewriters in YAML

Source: https://github.com/trickstercache/trickster/blob/main/docs/request_rewriters.md

Example configuration showing how to define named rewriters and use the chain instruction to execute one rewriter from another.

```yaml
request_rewriters:
  example_rewriter:
    instructions:
      - [ 'header', 'set', 'Cache-Control', 'max-age=60' ], # instruction 0
      - [ 'path', 'replace', '/cgi-bin/', '/' ],            # instruction 1
      - [ 'chain', 'exec', 'remove_accept_encoding' ]       # instruction 2

  remove_accept_encoding:
    instructions:
      - [ 'header', 'delete', 'Accept-Encoding' ] # instruction 0
```

--------------------------------

### Build and Test Trickster

Source: https://github.com/trickstercache/trickster/blob/main/CONTRIBUTING.md

Commands to build the Trickster project and run various tests. Ensure you have the necessary build tools installed.

```bash
# For building
make
./bin/trickster

# For testing.
make lint test data-race-test
```

--------------------------------

### Configure Redis Cache Backend (Sentinel)

Source: https://context7.com/trickstercache/trickster/llms.txt

Configuration for a Redis Sentinel setup. Includes client type, Sentinel endpoints, and the master name.

```yaml
# Redis Sentinel
redis-sentinel:
  provider: redis
  redis:
    client_type: sentinel
    endpoints:
      - sentinel-1:26379
      - sentinel-2:26379
    sentinel_master: mymaster
```

--------------------------------

### GET /trickster/config

Source: https://github.com/trickstercache/trickster/blob/main/docs/configuring.md

Retrieves the currently running Trickster configuration in YAML format.

```APIDOC
## GET /trickster/config

### Description
Returns the YAML output of the currently-running Trickster configuration, including defaults, file settings, command-line arguments, and environment variables.

### Method
GET

### Endpoint
/trickster/config

### Response
#### Success Response (200)
- **body** (string) - YAML-formatted configuration
```

--------------------------------

### Customizing Path Configs for Prometheus Backend

Source: https://github.com/trickstercache/trickster/blob/main/docs/paths.md

Example configuration showing how to override existing paths, add new routes, and block specific endpoints using the Trickster YAML configuration format.

```yaml
backends:
  default:
    provider: prometheus
    paths:
      # route /api/v1/label* (including /labels/*)
      # through Proxy instead of ProxyCache as pre-defined
      - path: /api/v1/label
        methods:
          - GET
        match_type: prefix
        handler: proxy
      # route fictional new /api/v1/coffee to ProxyCache
      - path: /api/v1/coffee
        methods:
          - GET
        match_type: prefix
        handler: proxycache
        cache_key_params:
          - beans
      # block /api/v1/admin/ from being reachable via Trickster
      - path: /api/v1/admin/
        methods:
          - GET
          - POST
          - PUT
          - HEAD
          - DELETE
          - OPTIONS
        match_type: prefix
        handler: localresponse
        response_code: 401
        response_body: No soup for you!
        no_metrics: true
```

--------------------------------

### Configure Trickster Distributed Tracing

Source: https://context7.com/trickstercache/trickster/llms.txt

Configure Trickster to export traces using the OTLP provider. This example shows how to set the endpoint and add custom tags, including omitting high-cardinality tags like http.url.

```yaml
tracing:
  my-jaeger-tracer:
    provider: otlp             # OTLP exporter (supports Jaeger and others)
    endpoint: http://jaeger:4318/v1/traces
    tags:
      environment: production
      service.version: "2.0"
    omit_tags:
      - http.url              # omit high-cardinality URL tag if needed

backends:
  default:
    provider: prometheus
    origin_url: http://prometheus:9090
    tracing_name: my-jaeger-tracer
```

--------------------------------

### Install Trickster via Helm

Source: https://github.com/trickstercache/trickster/blob/main/hack/release-notes/notes.md

Deploy Trickster to a Kubernetes cluster using the Trickster Helm chart. Note that the chart version is managed separately from the Trickster application version.

```bash
helm install trickster oci://ghcr.io/trickstercache/charts/trickster --version "^2" --set image.tag="${TAG}"
```

--------------------------------

### Generate Unique Query Expressions

Source: https://github.com/trickstercache/trickster/blob/main/integration/README.md

When sharing a Trickster boot across subtests, use unique query expressions to prevent OPC cache collisions. This example demonstrates generating a unique expression using the current nanosecond timestamp.

```go
fmt.Sprintf("up + 0*%d", time.Now().UnixNano())
```

--------------------------------

### Example Negative Caching Configuration

Source: https://github.com/trickstercache/trickster/blob/main/docs/negative-caching.md

Defines named negative cache maps and associates them with backends. The 'default' map caches 404s for 3 seconds, while the 'foo' map caches 404s for 3 seconds and 500/502 errors for 5 seconds. Backends can reference these named configurations.

```yaml
negative_caches:
  default:
    '404': 3s # cache 404 responses for 3 seconds
  foo:
    '404': 3s
    '500': 5s # caches 404 response for 3 seconds, and 500/502 for 5 seconds
    '502': 5s

backends:
  default:
    provider: rpc
    # by default will assume negative_cache_name = 'default'
  another:
    provider: rpc
    negative_cache_name: foo
```

--------------------------------

### Verify Trickster Docker Image Signature

Source: https://github.com/trickstercache/trickster/blob/main/README.md

Verifies the signature of a Trickster Docker image using cosign. Requires prior setup with the cosign quickstart guide.

```bash
cosign verify ghcr.io/trickstercache/trickster:x.y.z --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity=https://github.com/trickstercache/trickster/.github/workflows/publish-image.yaml@refs/tags/vx.y.z
```

--------------------------------

### Build Trickster Binary using Make

Source: https://github.com/trickstercache/trickster/blob/main/README.md

Builds the Trickster binary from source using Make. This method requires cloning the repository and having a Go environment set up.

```bash
$ mkdir -p $GOPATH/src/github.com/trickstercache
$ cd $GOPATH/src/github.com/trickstercache
$ git clone https://github.com/trickstercache/trickster.git
$ cd trickster
$ make build
$ ./bin/trickster -origin-url http://prometheus.example.com:9090 -provider prometheus
```

--------------------------------

### Run Integration Tests

Source: https://github.com/trickstercache/trickster/blob/main/integration/README.md

Navigate to the integration directory and use 'make test' to run the full suite of integration tests. Use 'make data-race-test' to run with the race detector enabled. Individual tests can be run using 'go test -run <TestName>'.

```sh
cd integration
make test
```

```sh
make data-race-test
```

```sh
go test -run TestALB
```

--------------------------------

### GET /trickster/config/reload

Source: https://github.com/trickstercache/trickster/blob/main/docs/configuring.md

Triggers a reload of the Trickster configuration file if changes are detected.

```APIDOC
## GET /trickster/config/reload

### Description
Triggers a reload of the Trickster configuration. If the underlying configuration file has changed, the configuration is reloaded. If no changes are detected, an unsuccessful response is returned, subject to the Reload Rate Limiter (default 3 seconds).

### Method
GET

### Endpoint
/trickster/config/reload
```

--------------------------------

### Build Trickster from Source via Makefile

Source: https://context7.com/trickstercache/trickster/llms.txt

Clone the Trickster repository, build the binary using 'make build', and then run the Trickster executable with specified flags.

```bash
git clone https://github.com/trickstercache/trickster.git
cd trickster
make build
./bin/trickster -origin-url http://prometheus.example.com:9090 -provider prometheus
```

--------------------------------

### Run Trickster Instant-Query Load Test

Source: https://github.com/trickstercache/trickster/blob/main/hack/load-test/README.md

Execute only the k6 test script simulating PromQL instant queries. This test focuses on the /api/v1/query endpoint.

```sh
make instant-query
```

--------------------------------

### Write Test Configuration

Source: https://github.com/trickstercache/trickster/blob/main/integration/README.md

Use this helper function within tests to clone the developer configuration and swap port assignments. This is useful for tests that require the full developer configuration but need unique port ranges to avoid conflicts.

```go
writeTestConfig()
```

--------------------------------

### Validate Trickster Configuration

Source: https://github.com/trickstercache/trickster/blob/main/docs/configuring.md

Run the application with the -validate-config flag to check the configuration file without starting the service.

```bash
trickster -validate-config -config /path/to/config
```

--------------------------------

### Create a new release tag

Source: https://github.com/trickstercache/trickster/blob/main/docs/developer/spinning-new-release.md

Use the Makefile target to tag a specific version. Ensure the version follows the vX.Y.Z semantic versioning format.

```bash
TAG_VERSION=v1.2.345 make create-tag
```

--------------------------------

### Get All Backends Health Summary (Plaintext)

Source: https://context7.com/trickstercache/trickster/llms.txt

Retrieve a human-readable summary of the health status for all configured Trickster backends.

```bash
# --- All backends health summary (plaintext) ---
curl http://trickster:8481/trickster/health
# Trickster Backend Health Status            last change: 2020-01-01 00:00:00 UTC
# -------------------------------------------------------------------------------
# prom-01      prometheus   available
# flux-01      influxdb     unavailable since 2020-01-01 00:00:00 UTC
# proxy-01     proxy        not configured for automated health checks
```

--------------------------------

### Define JSON Request Body for Cache Key

Source: https://github.com/trickstercache/trickster/blob/main/docs/paths.md

Example JSON document structure used for cache key derivation.

```json
{
    "requestType": "query",
    "query": {
        "table": "movies",
        "fields": "eidr,title",
        "filter": "year=1979"
    }
}
```

--------------------------------

### Configure Frontend and Backend TLS

Source: https://context7.com/trickstercache/trickster/llms.txt

Set up TLS termination for incoming client connections and configure outbound TLS for connections to upstream backends, including mutual TLS.

```yaml
frontend:
  listen_port: 8480
  tls_listen_port: 8483   # TLS listener; only active when at least one backend has a cert

backends:
  secure-backend:
    provider: reverseproxycache
    origin_url: https://secure.example.com
    tls:
      # Frontend TLS — serve this cert to incoming clients
      full_chain_cert_path: /path/to/fullchain.pem
      private_key_path: /path/to/privkey.pem
      # Backend TLS — configure outbound HTTPS client
      insecure_skip_verify: false        # analogous to curl -k
      certificate_authority_paths:
        - /path/to/custom-ca.pem
      client_cert_path: /path/to/client-cert.pem   # mutual TLS
      client_key_path: /path/to/client-key.pem
```

--------------------------------

### Get All Backends Health Summary (JSON)

Source: https://context7.com/trickstercache/trickster/llms.txt

Retrieve a machine-readable JSON object detailing the health status of all Trickster backends. Useful for automated monitoring.

```bash
# --- All backends health (JSON for machine consumption) ---
curl "http://trickster:8481/trickster/health?json" | jq
# {
#   "title": "Trickster Backend Health Status",
#   "updateTime": "2020-01-01 00:00:00 UTC",
#   "available": [{"name": "prom-01", "provider": "prometheus"}],
#   "unavailable": [{"name": "flux-01", "provider": "influxdb",
#                    "downSince": "...", "detail": "connection refused"}],
#   "unchecked": [{"name": "proxy-01", "provider": "proxy"}]
# }
```

--------------------------------

### Querying TSM ALB Backend

Source: https://context7.com/trickstercache/trickster/llms.txt

Example of how Grafana points to Trickster's TSM ALB backend for scatter/gather queries. The scatter/gather process is transparent to the client.

```bash
# Grafana points to Trickster's ALB backend; scatter/gather is transparent
curl "http://trickster:8480/prom-alb/api/v1/query_range?query=sum(rate(http_requests_total[5m]))&start=...&end=...&step=60"
# Trickster fans out to all 4 backends, auto-selects 'sum' merge strategy, returns merged result

```

--------------------------------

### Run Trickster Docker Container (Docker Hub)

Source: https://github.com/trickstercache/trickster/blob/main/README.md

Launches a Trickster Docker container using an image from Docker Hub. Ensure you have a trickster.yaml configuration file.

```bash
$ docker run --name trickster -d -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml -p 0.0.0.0:8480:8480 trickstercache/trickster
```

--------------------------------

### Validate Trickster Configuration File

Source: https://context7.com/trickstercache/trickster/llms.txt

Use the 'trickster' command with the '-validate-config' flag to check the syntax and structure of your Trickster configuration file without starting the service.

```bash
trickster -validate-config -config /path/to/trickster.yaml
```

--------------------------------

### Run Trickster with Docker

Source: https://context7.com/trickstercache/trickster/llms.txt

Use this command to run Trickster as a Docker container, mounting a configuration file and exposing the default port.

```bash
docker run --name trickster -d \
  -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml \
  -p 0.0.0.0:8480:8480 \
  trickstercache/trickster
```

```bash
docker run --name trickster -d \
  -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml \
  -p 0.0.0.0:8480:8480 \
  ghcr.io/trickstercache/trickster
```

--------------------------------

### Example of Negative Cache Hit

Source: https://context7.com/trickstercache/trickster/llms.txt

Demonstrates how a negative cache hit is indicated in the response headers. Subsequent requests for a cached error will be served from Trickster's cache.

```bash
# When origin returns 404, Trickster caches it for 3s
curl -I http://trickster:8480/missing-object
# HTTP/1.1 404 Not Found
# X-Trickster-Result: nchit    <-- subsequent requests served from negative cache
```

--------------------------------

### Cacheable Time Range WHERE Clauses

Source: https://github.com/trickstercache/trickster/blob/main/docs/clickhouse.md

Examples of WHERE clauses that Trickster can parse to determine the requested time range for cacheable queries. These include BETWEEN and >= operators with various time formats.

```sql
WHERE t >= "2020-10-15 00:00:00" and t <= "2020-10-16 12:00:00"
```

```sql
WHERE t >= "2020-10-15 12:00:00" and t < now() - 60 * 60
```

```sql
WHERE datetime BETWEEN 1574686300 AND 1574689900
```

--------------------------------

### ALB Configuration for Healthy Backends

Source: https://github.com/trickstercache/trickster/blob/main/docs/alb.md

Configure an ALB to route traffic only to backends reporting as 'available'. This example sets `healthy_floor: 1` and includes two Prometheus backends in the pool.

```yaml
backends:
  prom01:
    provider: prometheus
    origin_url: http://prom01.example.com:9090
    healthcheck:
      interval: 1000ms # enables automatic health check polling for ALB pool reporting

  prom02:
    provider: prometheus
    origin_url: http://prom02.example.com:9090
    healthcheck:
      interval: 1000ms

  prom-alb-tsm:
    provider: alb
    alb:
      mechanism: tsm   # times series merge healthy pool members
      healthy_floor: 1 # only include Backends reporting as 'available' in the healthy pool
      pool:
        - prom01
        - prom02
```

--------------------------------

### Basic Auth Authenticator Configuration

Source: https://github.com/trickstercache/trickster/blob/main/docs/authenticator.md

Configure a Basic Auth authenticator. Set `showLoginForm` to true to display a login form on failed authentication, otherwise a 401 Unauthorized is returned. The `realm` can be customized.

```yaml
example_auth_1:
  provider: basic
  users_file: "/path/to/trickster/users.htpasswd"
  showLoginForm: true
  realm: "custom-realm-name"
```

--------------------------------

### Scrape Trickster Prometheus Metrics

Source: https://context7.com/trickstercache/trickster/llms.txt

Example of how to scrape Trickster's own metrics endpoint using curl. Lists key metrics available for monitoring Trickster's performance and status.

```bash
# Scrape Trickster's own metrics
curl http://trickster:8481/metrics

# Key metrics:
# trickster_build_info{goversion,revision,version} gauge=1 when running
# trickster_frontend_requests_total{backend_name,provider,method,http_status,path}
# trickster_frontend_requests_duration_seconds{...} histogram
# trickster_proxy_requests_total{backend_name,provider,method,cache_status,http_status,path}
#   cache_status values: hit, kmiss, rmiss, phit, nchit, rhit, proxy-only, proxy-error
# trickster_proxy_points_total{backend_name,provider,cache_status,path}
# trickster_cache_operation_objects_total{cache_name,provider,operation,status}
# trickster_cache_operation_bytes_total{cache_name,provider,operation,status}
# trickster_cache_usage_objects{cache_name,provider}        gauge
# trickster_cache_usage_bytes{cache_name,provider}          gauge
# trickster_cache_max_usage_objects{cache_name,provider}    gauge
# trickster_cache_max_usage_bytes{cache_name,provider}      gauge
# trickster_config_last_reload_successful                   gauge (1=success, 0=fail)
# trickster_proxy_active_connections                        gauge
```

--------------------------------

### Configure Filesystem Cache Backend

Source: https://context7.com/trickstercache/trickster/llms.txt

Configuration for a filesystem cache. Sets the cache path, and parameters for the index, including size limit, reap interval, and flush interval.

```yaml
# Filesystem cache
fs-cache:
  provider: filesystem
  filesystem:
    cache_path: /var/cache/trickster
  index:
    max_size_bytes: 536870912
    reap_interval: 3s
    flush_interval: 5s
```

--------------------------------

### HTTP Reverse Proxy Cache Configuration

Source: https://context7.com/trickstercache/trickster/llms.txt

Configure Trickster as a general-purpose HTTP reverse proxy with caching. This example shows per-path configuration for different handlers like proxy-only and proxy-cache.

```yaml
# trickster.yaml — reverse proxy cache with per-path configuration
frontend:
  listen_port: 8480

backends:
  default:
    provider: reverseproxycache   # use 'reverseproxy' for proxy-only (no caching)
    origin_url: https://www.example.com
    paths:
      - path: / "
        methods: ['*']
        match_type: prefix
        handler: proxy             # proxy-only, no caching
        request_params:
          authToken: ${ROOT_REQUEST_AUTH_TOKEN}  # env-var substitution
        request_headers:
          Cache-Control: No-Transform
        response_headers:
          Expires: '-1'
      - path: /images/
        methods: [GET, HEAD]
        handler: proxycache        # cache this path
        match_type: prefix
        response_headers:
          Cache-Control: max-age=2592000   # 30 days
      - path: /images/rotating.jpg
        methods: [GET]
        handler: proxycache
        match_type: exact
        response_headers:
          Cache-Control: max-age=30
          '-Expires': ''           # remove Expires header
      - path: /blog
        methods: ['*']
        handler: localresponse     # serve locally without hitting origin
        match_type: prefix
        response_code: 302
        response_headers:
          Location: /discontinued
      - path: /api/
        methods: [GET, HEAD, POST]
        handler: proxycache
        match_type: prefix
        cache_key_params: [query]
        cache_key_form_fields: [query]  # include POST body fields in cache key
      - path: /api/
        methods: [POST, PUT, PATCH, DELETE, OPTIONS, CONNECT]
        handler: localresponse
        match_type: prefix
        response_code: 401
        response_body: this is a read-only api endpoint
      - path: /stream/
        methods: [GET]
        handler: proxycache
        match_type: prefix
        collapsed_forwarding: progressive  # Progressive Collapsed Forwarding
```

--------------------------------

### Set Port

Source: https://github.com/trickstercache/trickster/blob/main/docs/request_rewriters.md

Sets the request's port.

```text
['port', 'set', '8480']
```

--------------------------------

### Plain Text Health Status Page Output

Source: https://github.com/trickstercache/trickster/blob/main/docs/alb.md

Example output from the Trickster global health status page. It shows the health state of configured backends, indicating if they are available, unavailable, or not checked.

```text
$ curl "http://${trickster-fqdn}:8481/trickster/health"

Trickster Backend Health Status            last change: 2020-01-01 00:00:00 UTC
-------------------------------------------------------------------------------

prom-01      prometheus   available

flux-01      influxdb     unavailable since 2020-01-01 00:00:00 UTC
                                    
proxy-01     proxy        not configured for automated health checks

-------------------------------------------------------------------------------
You can also provide a 'Accept: application/json' Header or query param ?json
```

--------------------------------

### Run Trickster Docker Container (GHCR)

Source: https://github.com/trickstercache/trickster/blob/main/README.md

Launches a Trickster Docker container using an image from GitHub Container Registry. Ensure you have a trickster.yaml configuration file.

```bash
$ docker run --name trickster -d -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml -p 0.0.0.0:8480:8480 ghcr.io/trickstercache/trickster
```

--------------------------------

### Parameter Rewriter Instructions

Source: https://github.com/trickstercache/trickster/blob/main/docs/request_rewriters.md

Instructions for modifying URL query parameters.

```APIDOC
## Parameter Rewriter Instructions

Modifies the URL Query Parameter of the specified name.

### `param set`

Sets the URL Query Parameter of the provided name to the provided value.

**Format:**
```
['param', 'set', 'paramName', 'new param value']
```

### `param replace`

Performs a search/replace function on the URL Query Parameter value of the provided name.

**Format:**
```
['param', 'replace', 'paramName', 'search value', 'replacement value']
```

### `param delete`

Removes, if present, the URL Query Parameter of the provided name.

**Format:**
```
['param', 'delete', 'paramName']
```
```