README
¶
Trickster is an HTTP reverse proxy/cache for http applications and a dashboard query accelerator for time series databases.
Learn more below, and check out our roadmap to find out what else is in the works.
Trickster is hosted by the Cloud Native Computing Foundation (CNCF) as a sandbox level project. If you are a company that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF.
Note: Trickster v1.1 is the production release, sourced from the v1.1.x branch. The main branch sources Trickster 2.0, which is currently in beta.
HTTP Reverse Proxy Cache
Trickster is a fully-featured HTTP Reverse Proxy Cache for HTTP applications like static file servers and web API's.
Proxy Feature Highlights
- A unique and powerful Application Load Balancer for Time Series and generic HTTP endpoints
- Supports TLS and HTTP/2 for frontend termination and backend origination
- Offers several options for a caching layer, including in-memory, filesystem, Redis and bbolt
- Highly customizable, using simple yaml configuration settings, down to the HTTP Path
- Built-in Prometheus metrics and customizable Health Check Endpoints for end-to-end monitoring
- Negative Caching to prevent domino effect outages
- High-performance Collapsed Forwarding
- Best-in-class Byte Range Request caching and acceleration.
- Distributed Tracing via OpenTelemetry, supporting OTLP protocol.
- Rules engine for custom request routing and rewriting
- Configurable maximum request body size.
Time Series Database Accelerator
Trickster dramatically improves dashboard chart rendering times for end users by eliminating redundant computations on the TSDBs it fronts. In short, Trickster makes read-heavy Dashboard/TSDB environments, as well as those with highly-cardinalized datasets, significantly more performant and scalable.
Compatibility
Trickster works with virtually any Dashboard application that makes queries to any of these TSDB's:
Prometheus
ClickHouse
InfluxDB
See the Supported TSDB Providers document for full details
How Trickster Accelerates Time Series
1. Time Series Delta Proxy Cache
Most dashboards request from a time series database the entire time range of data they wish to present, every time a user's dashboard loads, as well as on every auto-refresh. Trickster's Delta Proxy inspects the time range of a client query to determine what data points are already cached, and requests from the tsdb only the data points still needed to service the client request. This results in dramatically faster chart load times for everyone, since the tsdb is queried only for tiny incremental changes on each dashboard load, rather than several hundred data points of duplicative data.
2. Step Boundary Normalization
When Trickster requests data from a tsdb, it adjusts the clients's requested time range slightly to ensure that all data points returned are aligned to normalized step boundaries. For example, if the step is 300s, all data points will fall on the clock 0's and 5's. This ensures that the data is highly cacheable, is conveyed visually to users in a more familiar way, and that all dashboard users see identical data on their screens.
3. Fast Forward
Trickster's Fast Forward feature ensures that even with step boundary normalization, real-time graphs still always show the most recent data, regardless of how far away the next step boundary is. For example, if your chart step is 300s, and the time is currently 1:21p, you would normally be waiting another four minutes for a new data point at 1:25p. Trickster will break the step interval for the most recent data point and always include it in the response to clients requesting real-time data.
Trying Out Trickster
Check out our end-to-end Docker Compose demo composition for a zero-configuration running environment.
Installing
Docker
Docker images are available on Docker Hub (docker.io):
$ docker run --name trickster -d -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml -p 0.0.0.0:8480:8480 trickstercache/trickster
Or via Github Container Registry (ghcr.io):
$ 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
Verifying Docker Image
To verify that the Trickster Docker image is running, first walk through the cosign quickstart guide.
To verify a trickster image, you can use the following command:
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
See the 'deploy' Directory for more information about using or creating Trickster docker images.
Kubernetes
See the 'deploy' Directory for Kube and deployment files and examples.
Helm
Trickster Helm Charts are located at https://helm.trickstercache.org/ for installation, and maintained at https://github.com/trickstercache/helm-charts. We welcome chart contributions.
Building from source
To build Trickster from the source code yourself you need to have a working Go environment with version 1.26 or greater installed.
You can directly use the go tool to download and install the trickster
binary into your GOPATH:
$ 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
You can also clone the repository yourself and build using make:
$ 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
The Makefile provides several targets, including:
- build: build the
tricksterbinary - docker: build a docker container for the current
HEAD - clean: delete previously-built binaries and object files
- test: runs unit tests
- bench: runs benchmark tests
- rpm: builds a Trickster RPM
More information
- Refer to the docs directory for additional info.
Contributing
Refer to CONTRIBUTING.md
© 2021 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
trickster
command
Package main is the main package for the Trickster application
|
Package main is the main package for the Trickster application |
|
examples
|
|
|
packages/cache/bbolt
command
|
|
|
packages/cache/memory
command
|
|
|
pkg
|
|
|
appinfo
Package app holds application build information
|
Package app holds application build information |
|
backends
Package backends the interface and generic functionality for Backend providers
|
Package backends the interface and generic functionality for Backend providers |
|
backends/alb
Package alb implements the Application Load Balancer Backend
|
Package alb implements the Application Load Balancer Backend |
|
backends/alb/mech
Package mech provides the ALB Mechanisms functionality
|
Package mech provides the ALB Mechanisms functionality |
|
backends/alb/mech/fanout
Package fanout is the shared primitive for ALB mechanisms that scatter a single inbound request to N pool members and gather their responses.
|
Package fanout is the shared primitive for ALB mechanisms that scatter a single inbound request to N pool members and gather their responses. |
|
backends/alb/pool
Package pool provides an application load balancer pool
|
Package pool provides an application load balancer pool |
|
backends/clickhouse
Package clickhouse provides the ClickHouse backend provider
|
Package clickhouse provides the ClickHouse backend provider |
|
backends/clickhouse/authenticator
Package authenticator provides an Authenticator implementation for ClickHouse.
|
Package authenticator provides an Authenticator implementation for ClickHouse. |
|
backends/influxdb
Package influxdb provides the InfluxDB Backend provider
|
Package influxdb provides the InfluxDB Backend provider |
|
backends/influxdb/iofmt
package iofmt assists with managing supported input and output formats across the various versions of InfluxDB
|
package iofmt assists with managing supported input and output formats across the various versions of InfluxDB |
|
backends/prometheus
Package prometheus provides the Prometheus Backend provider
|
Package prometheus provides the Prometheus Backend provider |
|
backends/prometheus/promql
Package promql provides utilities for parsing and rewriting PromQL queries.
|
Package promql provides utilities for parsing and rewriting PromQL queries. |
|
backends/reverseproxy
Package reverseproxy provides the HTTP Reverse Proxy (no caching) Backend provider
|
Package reverseproxy provides the HTTP Reverse Proxy (no caching) Backend provider |
|
backends/reverseproxycache
Package reverseproxycache provides the HTTP Reverse Proxy Cache Backend provider
|
Package reverseproxycache provides the HTTP Reverse Proxy Cache Backend provider |
|
backends/tree
Package tree provides data structures that define the possible paths through chained Backends to assist with config Validation
|
Package tree provides data structures that define the possible paths through chained Backends to assist with config Validation |
|
cache
Package cache defines the Trickster cache interfaces and provides general cache functionality
|
Package cache defines the Trickster cache interfaces and provides general cache functionality |
|
cache/badger
Package badger is the BadgerDB implementation of the Trickster Cache
|
Package badger is the BadgerDB implementation of the Trickster Cache |
|
cache/bbolt
Package bbolt is the bbolt implementation of the Trickster Cache
|
Package bbolt is the bbolt implementation of the Trickster Cache |
|
cache/filesystem
Package filesystem is the filesystem implementation of the Trickster Cache
|
Package filesystem is the filesystem implementation of the Trickster Cache |
|
cache/index
Package index defines the Trickster Cache Index
|
Package index defines the Trickster Cache Index |
|
cache/memory
Package memory is the memory implementation of the Trickster Cache and uses ristretto (TinyLFU admission-controlled cache) to manage cache objects
|
Package memory is the memory implementation of the Trickster Cache and uses ristretto (TinyLFU admission-controlled cache) to manage cache objects |
|
cache/negative
Package negative defines the Negative Cache which is a simple lookup map of httpStatus to TTL
|
Package negative defines the Negative Cache which is a simple lookup map of httpStatus to TTL |
|
cache/redis
Package redis is the redis implementation of the Trickster Cache and supports Standalone, Sentinel and Cluster
|
Package redis is the redis implementation of the Trickster Cache and supports Standalone, Sentinel and Cluster |
|
cache/registry
Package registry handles the registration of cache implementations to be used by proxy cache handlers
|
Package registry handles the registration of cache implementations to be used by proxy cache handlers |
|
cache/status
Package status governs the possible Cache Lookup Status values
|
Package status governs the possible Cache Lookup Status values |
|
checksum/fnv
Package fnv implements the Fowler Noll Vo hash function (version a) taken with much appreciation from, and giving all credit to: https://github.com/influxdata/influxdb/blob/v1.8.0/models/inline_fnv.go
|
Package fnv implements the Fowler Noll Vo hash function (version a) taken with much appreciation from, and giving all credit to: https://github.com/influxdata/influxdb/blob/v1.8.0/models/inline_fnv.go |
|
checksum/md5
Package md5 provides string-based checksum functionality
|
Package md5 provides string-based checksum functionality |
|
checksum/sha1
Package sha1 provides string-based checksum functionality
|
Package sha1 provides string-based checksum functionality |
|
config
Package config provides Trickster configuration abilities, including parsing and printing configuration files, command line parameters, and environment variables, as well as default values and state.
|
Package config provides Trickster configuration abilities, including parsing and printing configuration files, command line parameters, and environment variables, as well as default values and state. |
|
config/reload
Package reload helps with reloading the running Trickster configuration
|
Package reload helps with reloading the running Trickster configuration |
|
daemon
package server runs the Trickster process as an HTTP(S) Listener based on the provided configuration
|
package server runs the Trickster process as an HTTP(S) Listener based on the provided configuration |
|
encoding/gzip
Package gzip provides gzip capabilities for byte slices
|
Package gzip provides gzip capabilities for byte slices |
|
encoding/zlib
Package zlib provides zlib (RFC 1950) capabilities for byte slices.
|
Package zlib provides zlib (RFC 1950) capabilities for byte slices. |
|
observability/logging/logger
package logger provides a package-level logger for application-wide use, and provides all of the same functions of logging.Logger at the package level - except for Close() (because this logger should always be open).
|
package logger provides a package-level logger for application-wide use, and provides all of the same functions of logging.Logger at the package level - except for Close() (because this logger should always be open). |
|
observability/metrics
Package metrics implements prometheus metrics and exposes the metrics HTTP listener
|
Package metrics implements prometheus metrics and exposes the metrics HTTP listener |
|
observability/tracing
Package tracing provides distributed tracing services to Trickster
|
Package tracing provides distributed tracing services to Trickster |
|
observability/tracing/errors
Package errors provides tracing errors
|
Package errors provides tracing errors |
|
observability/tracing/exporters/noop
Package noop provides a Noop Tracer
|
Package noop provides a Noop Tracer |
|
observability/tracing/exporters/otlp
Package otlp provides a OTLP Tracer
|
Package otlp provides a OTLP Tracer |
|
observability/tracing/exporters/stdout
Package stdout provides a Stdout Tracer
|
Package stdout provides a Stdout Tracer |
|
observability/tracing/registry
Package registration registers configured tracers for use with handlers
|
Package registration registers configured tracers for use with handlers |
|
parsing/sql
Package sql provides a basic SQL SQLParser that can be extended by individual implementations.
|
Package sql provides a basic SQL SQLParser that can be extended by individual implementations. |
|
proxy
Package proxy provides all proxy services for Trickster
|
Package proxy provides all proxy services for Trickster |
|
proxy/authenticator
Package authenticator provides implementations of Authenticators
|
Package authenticator provides implementations of Authenticators |
|
proxy/context
Package context manages the insertion of Request-specific information (which cache to use, etc.) into proxied HTTP requests
|
Package context manages the insertion of Request-specific information (which cache to use, etc.) into proxied HTTP requests |
|
proxy/engines
Package engines provides the Reverse Proxy, Reverse Proxy Cache, and Time Series Delta Proxy Cache features for use by handlers.
|
Package engines provides the Reverse Proxy, Reverse Proxy Cache, and Time Series Delta Proxy Cache features for use by handlers. |
|
proxy/errors
Package errors provides common Error functionality to the Trickster proxy
|
Package errors provides common Error functionality to the Trickster proxy |
|
proxy/handlers
Package handlers provides several non-proxy handlers for use internally by other Trickster handlers
|
Package handlers provides several non-proxy handlers for use internally by other Trickster handlers |
|
proxy/handlers/health
Package health provides an application-wide health handler endpoint that is usually mapped to /trickster/health and provides the health status of the application's configured proxy endpoints
|
Package health provides an application-wide health handler endpoint that is usually mapped to /trickster/health and provides the health status of the application's configured proxy endpoints |
|
proxy/headers
Package headers provides functionality for HTTP Headers not provided by the builtin net/http package
|
Package headers provides functionality for HTTP Headers not provided by the builtin net/http package |
|
proxy/methods
Package methods provides functionality for handling HTTP methods
|
Package methods provides functionality for handling HTTP methods |
|
proxy/params
Package params provides support for handling URL Parameters
|
Package params provides support for handling URL Parameters |
|
proxy/ranges/byterange
Package byterange provides acceleration functions for Byte Ranges for use with HTTP Range Requests
|
Package byterange provides acceleration functions for Byte Ranges for use with HTTP Range Requests |
|
proxy/request
Package request provides functionality for handling HTTP Requests including the insertion of configuration options into the request
|
Package request provides functionality for handling HTTP Requests including the insertion of configuration options into the request |
|
proxy/router
package router provides an interface for routing HTTP requests to handlers
|
package router provides an interface for routing HTTP requests to handlers |
|
proxy/router/lm
package lm represents a simple Longest Match router
|
package lm represents a simple Longest Match router |
|
proxy/router/route
package route provides a Route data structure for Request Routing
|
package route provides a Route data structure for Request Routing |
|
proxy/tls
Package tls handles options for TLS (https) requests
|
Package tls handles options for TLS (https) requests |
|
proxy/urls
Package urls provides capabilities for manipulating URLs that are not provided by the builtin net/url package
|
Package urls provides capabilities for manipulating URLs that are not provided by the builtin net/url package |
|
routing
Package routing is the Trickster Request Router
|
Package routing is the Trickster Request Router |
|
testutil
Package testing provides functionality for use when conducting tests
|
Package testing provides functionality for use when conducting tests |
|
testutil/albpool
Package albpool provides shared test helpers for constructing ALB pools, targets, and parent requests.
|
Package albpool provides shared test helpers for constructing ALB pools, targets, and parent requests. |
|
testutil/golden
Package golden holds JSON-fixture helpers for tests that maintain testdata/ goldens.
|
Package golden holds JSON-fixture helpers for tests that maintain testdata/ goldens. |
|
testutil/timeseries/model
Package model is a test utility package that serializes between a *DataSet and the Prometheus HTTP API JSON Format
|
Package model is a test utility package that serializes between a *DataSet and the Prometheus HTTP API JSON Format |
|
testutil/tls
Package tls provides functionality for use when conducting tests with TLS
|
Package tls provides functionality for use when conducting tests with TLS |
|
testutil/writer
package writer represents a Test ResponseWriter for use in Unit Tests
|
package writer represents a Test ResponseWriter for use in Unit Tests |
|
timeseries
Package timeseries defines the interface for managing time seres objects and provides time range manipulation capabilities
|
Package timeseries defines the interface for managing time seres objects and provides time range manipulation capabilities |
|
timeseries/dataset
Package dataset defines the interface for managing time seres objects and provides time range manipulation capabilities
|
Package dataset defines the interface for managing time seres objects and provides time range manipulation capabilities |
|
timeseries/sqlparser
Package sqlparser provides customizations to the base sql parser that are specific to timeseries (for example, parsing trickster directives from comments)
|
Package sqlparser provides customizations to the base sql parser that are specific to timeseries (for example, parsing trickster directives from comments) |
|
util
Package util provides utility sub-packages to Trickster
|
Package util provides utility sub-packages to Trickster |
|
util/middleware
Package middleware provides middleware functions used by the Router during registration to construct handler chains
|
Package middleware provides middleware functions used by the Router during registration to construct handler chains |
|
util/regexp/matching
Package matching provides patterns for processing regexp.Regexp matches
|
Package matching provides patterns for processing regexp.Regexp matches |
|
util/safego
Package safego spawns goroutines whose panics must not crash the process.
|
Package safego spawns goroutines whose panics must not crash the process. |
|
util/strings
Package strings provides extended functionality for string types
|
Package strings provides extended functionality for string types |
|
util/timeconv
Package timeconv provides time conversion capabilities to Trickster
|
Package timeconv provides time conversion capabilities to Trickster |
Click to show internal directories.
Click to hide internal directories.