You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jul 22, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+4-3Lines changed: 4 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,10 +7,11 @@ One might ask why, in the presence of so many available collectors ([Zipkin](htt
7
7
Listed below are some reasons why *foxx-tracer-collector* was created:
8
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
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.
10
+
1. All existing CommonJS OpenTracing client libraries are naturally asynchronous in order to avoid this penalty, but this also means they cannot run within a Foxx V8 context. Therefore, a 100% synchronous client library is also required. This requirement is fulfilled by [foxx-tracer](https://github.com/RecallGraph/foxx-tracer) - a companion client library for *foxx-tracer-collector*.
11
+
1. One way to achieve asynchronous execution in Foxx 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.
12
+
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), which make an in-memory trace-buffering mechanism (with periodic, task-based flush) unfeasible.
12
13
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
+
1. This is where *foxx-tracer-collector* comes to the rescue. It runs beside your traced service in the same DB instance, and works in tandem with the *foxx-tracer* client (installed in your service) to record spans by means of an exported function that is**directly invoked** (in-process) and returns instantly, with no blocking I/O performed.
14
15
15
16
## How it works
16
17
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.
0 commit comments