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.
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
- 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 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 Jaeger and Zipkin
- Rules engine for custom request routing and rewriting
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
Circonus IRONdb
See the Supported Origin Types 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 run --name trickster -d -v /path/to/trickster.conf:/etc/trickster/trickster.conf -p 0.0.0.0:8480:8480 tricksterproxy/trickster
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.tricksterproxy.io for installation, and maintained at https://github.com/tricksterproxy/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.9 or greater installed.
You can directly use the go tool to download and install the trickster
binary into your GOPATH:
$ go get github.com/tricksterproxy/trickster
$ trickster -origin-url http://prometheus.example.com:9090 -origin-type prometheus
You can also clone the repository yourself and build using make:
$ mkdir -p $GOPATH/src/github.com/tricksterproxy
$ cd $GOPATH/src/github.com/tricksterproxy
$ git clone https://github.com/tricksterproxy/trickster.git
$ cd trickster
$ make build
$ ./OPATH/trickster -origin-url http://prometheus.example.com:9090 -origin-type 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
Who Is Using Trickster
As the Trickster community grows, we'd like to keep track of who is using it in their stack. We invite you to submit a PR with your company name and @githubhandle to be included on the list.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
trickster
Package main is the main package for the Trickster application
|
Package main is the main package for the Trickster application |
|
pkg
|
|
|
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 a sync.Map to manage cache objects
|
Package memory is the memory implementation of the Trickster Cache and uses a sync.Map to manage cache objects |
|
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/registration
Package registration handles the registration of cache implementations to be used by proxy cache handlers
|
Package registration 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 |
|
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 |
|
config/reload/options
Package options provides options for configuration reload support
|
Package options provides options for configuration reload support |
|
locks
Package locks provides Named Locks functionality for manging mutexes by string name (e.g., cache keys).
|
Package locks provides Named Locks functionality for manging mutexes by string name (e.g., cache keys). |
|
proxy
Package proxy provides all proxy services for Trickster
|
Package proxy provides all proxy services for Trickster |
|
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/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/origins
Package origins the interface and generic functionality for Origin Types
|
Package origins the interface and generic functionality for Origin Types |
|
proxy/origins/clickhouse
Package clickhouse provides the ClickHouse origin type
|
Package clickhouse provides the ClickHouse origin type |
|
proxy/origins/influxdb
Package influxdb provides the InfluxDB Origin Type
|
Package influxdb provides the InfluxDB Origin Type |
|
proxy/origins/irondb
Package irondb provides proxy origin support for IRONdb databases.
|
Package irondb provides proxy origin support for IRONdb databases. |
|
proxy/origins/prometheus
Package prometheus provides the Prometheus Origin Type
|
Package prometheus provides the Prometheus Origin Type |
|
proxy/origins/reverseproxycache
Package reverseproxycache provides the HTTP Reverse Proxy Cache Origin Type
|
Package reverseproxycache provides the HTTP Reverse Proxy Cache Origin Type |
|
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/timeconv
Package timeconv provides time conversion capabilities to Trickster
|
Package timeconv provides time conversion capabilities to Trickster |
|
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 |
|
runtime
Package runtime holds application runtime information
|
Package runtime holds application runtime information |
|
sort/floats
Package floats provides sorting capabilities to a slice of type float64
|
Package floats provides sorting capabilities to a slice of type float64 |
|
sort/times
Package times provides sorting capabilities to a slice of type time
|
Package times provides sorting capabilities to a slice of type time |
|
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 |
|
tracing
Package tracing provides distributed tracing services to Trickster
|
Package tracing provides distributed tracing services to Trickster |
|
tracing/errors
Package errors provides tracing errors
|
Package errors provides tracing errors |
|
tracing/exporters/jaeger
Package jaeger provides a Jager Tracer
|
Package jaeger provides a Jager Tracer |
|
tracing/exporters/noop
Package noop provides a Noop Tracer
|
Package noop provides a Noop Tracer |
|
tracing/exporters/stdout
Package stdout provides a Stdout Tracer
|
Package stdout provides a Stdout Tracer |
|
tracing/exporters/zipkin
Package zipkin provides a Zipkin Tracer
|
Package zipkin provides a Zipkin Tracer |
|
tracing/registration
Package registration registers configured tracers for use with handlers
|
Package registration registers configured tracers for use with handlers |
|
util
Package util provides utility sub-packages to Trickster
|
Package util provides utility sub-packages to Trickster |
|
util/compress/gzip
Package gzip provides gzip capabilities for byte slices
|
Package gzip provides gzip capabilities for byte slices |
|
util/log
Package log provides logging functionality to Trickster
|
Package log provides logging functionality to Trickster |
|
util/md5
Package md5 provides string-based checksum functionality
|
Package md5 provides string-based checksum functionality |
|
util/metrics
Package metrics implements prometheus metrics and exposes the metrics HTTP listener
|
Package metrics implements prometheus metrics and exposes the metrics HTTP listener |
|
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
|
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/sha1
Package sha1 provides string-based checksum functionality
|
Package sha1 provides string-based checksum functionality |
|
util/strings
Package strings provides extended functionality for string types
|
Package strings provides extended functionality for string types |
|
util/testing
Package testing provides functionality for use when conducting tests
|
Package testing provides functionality for use when conducting tests |
|
util/testing/tls
Package tls provides functionality for use when conducting tests with TLS
|
Package tls provides functionality for use when conducting tests with TLS |