|
1 | 1 | # foxx-tracer-collector |
2 | | -A collector service for foxx-tracer |
| 2 | +A Foxx microservice that acts as a collector agent for [OpenTracing](https://opentracing.io/) [spans](https://opentracing.io/specification/#the-opentracing-api) emitted by [foxx-tracer](https://github.com/RecallGraph/foxx-tracer). |
| 3 | + |
| 4 | +## Why another collector agent? |
| 5 | +One might ask why, in the presence of so many available collectors ([Zipkin](https://zipkin.io/pages/architecture.html#zipkin-collector), [OpenCensus Collector](https://opencensus.io/service/components/collector/), [Jaeger](https://www.jaegertracing.io/docs/1.18/architecture/#collector), etc.) do we need another collector service. |
| 6 | + |
| 7 | +Listed below are some reasons why *foxx-tracer-collector* was created: |
| 8 | +1. Traces (a trace is a collection of interrelated spans) generated inside a [Foxx Microservice](https://www.arangodb.com/docs/stable/foxx.html) have to be shipped out to an external system where they can be stored and analyzed. Unfortunately, the Foxx runtime is extremely restrictive about how its mounted services can communicate with the outside world. |
| 9 | +1. The only allowed networking option is to use Foxx's built-in [request](https://www.arangodb.com/docs/stable/foxx-guides-making-requests.html) module, but that too is entirely synchronous - meaning we cannot insert trace-posting requests in the main execution path without severely degrading latency and throughput metrics. |
| 10 | +1. A workaround to achieving asynchronicity is to use the [Task API](https://www.arangodb.com/docs/3.6/appendix-java-script-modules-tasks.html), but that would mean burdening the service with continually generating asynchronous tasks just to push out trace data, which is not its primary function. |
| 11 | +1. There are other, more nuanced limitations imposed by the 100% synchronous runtime that distributes a service deployment across multiple, isolated V8 contexts (in singular instances as well as in clusters) as well as the way the Task API works, which make an in-memory trace-buffering mechanism (with periodic, task-based flush) unfeasible. |
| 12 | +1. Due to the reasons stated above, every trace that is initiated by an incoming request has to be flushed immediately once the request has been served. Naturally, this must be done with as little lag as possible. |
| 13 | +1. This is where *foxx-tracer-collector* comes to the rescue. It runs beside your traced service in the same DB instance, and exports a function to record spans that can be **directly invoked** (in-process) and returns instantly, with no blocking I/O performed. |
| 14 | + |
| 15 | +## How it works |
| 16 | +Once a trace has been offloaded to the collector, your service is free to go back to its primary business, which is to serve user requests. |
| 17 | + |
| 18 | +The collector, in turn, asynchronously persists the trace to DB (via the Tasks API), and then periodically pushes all pending traces to designated endpoints (via pluggable [reporters](#reporters)). Recorded traces are assigned a configurable TTL, after which they are expunged from the database, thereby keeping things light and nimble. |
| 19 | + |
| 20 | +## Reporters |
| 21 | +*foxx-tracer-collector* uses a system of pluggable *reporters* to push its received traces to various destinations. More than one reporter can be active at a time, in which case all of them are invoked to push the traces to their respective endpoints. |
| 22 | + |
| 23 | +The collector comes with two reporters pre-installed: |
| 24 | +1. A *noop* reporter that does nothing. This reporter cannot be removed, but it can be disabled. |
| 25 | +1. A [console reporter](https://github.com/RecallGraph/foxx-tracer-reporter-console) that prints traces to the ArangoDB log. This reporter can be removed or disabled if required. |
| 26 | + |
| 27 | +Neither of these reporters is particularly useful for production setups, but are useful for debugging purposes. |
| 28 | + |
| 29 | +More useful (for actual trace capture and analysis) reporters can be found by searching the [NPM registry](https://www.npmjs.com/) for the keyword **"foxx-tracer-reporter"**. At the time of this writing, there is a production-ready reporter available for the [Datadog Cloud Monitoring Service](https://www.datadoghq.com/) service. It is named [foxx-tracer-reporter-datadog](https://github.com/RecallGraph/foxx-tracer-reporter-datadog). |
| 30 | + |
| 31 | +### Custom Reporters |
| 32 | +If you don't find a reporter for your specific endpoint, you can easily [write one yourself](https://github.com/RecallGraph/foxx-tracer-reporter-console#writing-your-own-reporter)! |
| 33 | + |
| 34 | +## Installation and Configuration |
| 35 | +See the [wiki](https://github.com/RecallGraph/foxx-tracer-collector/wiki) for instructions. |
0 commit comments