Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
1# API Server
2
3## Available Scripts
4
5- `npm start` will start the server locally in watch mode. Just make sure that Redis and Postgres are running locally, and your `.env` file has the relevant connection settings to reach them.
6- `npm run runWorkerOrJob [workerName] | [jobName]` will run a specific worker or job, which aren't run at all when using `npm run start`. The current set of workers and jobs, and therefore legal arguments for this script, are in the `workers_jobs` directory, besides `index.ts` and `dbTypes.ts`.
7
8 ## Tracing/Logging
9
10Coop uses distributed tracing (OpenTelemetry) for observability. Direct logging via `console.*` is disabled by lint rules. Instead, attach log messages to spans for better correlation and debugging.
11
12### Inject Tracer
13
14This is the canonical way we are obtaining a tracer object. This class comes with custom convenience methods. Implementation can be found [here](./utils/SafeTracer.ts).
15
16```js
17class ActionAPI extends DataSource {
18 constructor(
19 private readonly tracer: Dependencies['Tracer'],
20 ){}
21}
22...
23export default inject(
24 [
25 'Tracer',
26 ],
27 ActionAPI,
28);
29```
30
31### Add Active Span
32
33Sometimes you may want to capture a unit of work in its own span in which case you can use `addActiveSpan`.
34
35```js
36 return tracer.addActiveSpan(
37 { resource: 'dataWarehouse.query', operation: 'query' },
38 (span) => {
39 // do work
40 }
41 );
42```
43
44### Record Exception
45
46This will add the exception as an event to the given span without marking the span as failed. This can be useful when an exception does not necessarily entail the entire operation has failed, e.g. when one iteration of a loop fails but you want to continue processing the remaining elements.
47
48```js
49 catch (exception) {
50 span.recordException(exception as Exception);
51 }
52```
53
54### [Legacy] Mark Active Span as Failed
55
56This will record an exception by adding it as an attribute to the active span as well as mark that span as FAILED.
57
58This is considered legacy because a piece of code generally shouldn't be setting the status of a span that it didn't create, which is what's happening when the code reaches for the active span in this way.
59
60```js
61catch (e: unknown) {
62 Tracer.logActiveSpanFailedIfAny(e);
63}
64```
65