| 1 | # event-sdk
|
| 2 |
|
| 3 | **EXPERIMENTAL** Event SDK for Clients & Server implementations
|
| 4 |
|
| 5 | [](https://github.com/mojaloop/event-sdk/commits/master)
|
| 6 | [](https://github.com/mojaloop/event-sdk/releases)
|
| 7 | [](https://www.npmjs.com/package/@mojaloop/event-sdk)
|
| 8 | [](https://www.npmjs.com/package/@mojaloop/event-sdk)
|
| 9 | [](https://circleci.com/gh/mojaloop/event-sdk)
|
| 10 |
|
| 11 | Mojaloop Event SDK provides a simple API to log different kind of messages ( trace, log, error, audit ) and publish them to a central logging infrastructure.
|
| 12 |
|
| 13 | The API is defined by the `EventRecorder` interface and the `EventMessage` type.
|
| 14 | This library provides the following recorder implementations by default:
|
| 15 |
|
| 16 | | Recorder | Behaviour |
|
| 17 | | - | - |
|
| 18 | | `DefaultLoggerRecorder` | Logs events to console |
|
| 19 | | `DefaultSidecarRecorder` | Logs events to [sidecar](https://github.com/mojaloop/event-sidecar) synchronously |
|
| 20 | | `DefaultSidecarRecorderAsync` | Logs events to [sidecar](https://github.com/mojaloop/event-sidecar) asynchronously |
|
| 21 |
|
| 22 | The logging behaviour can be modified as defined in the interfaces `EventPreProcessor` and `EventPostProcessor` which allow to use an `EventRecorder` that processes `EventMessage`s before sending them and its response, respectively.
|
| 23 |
|
| 24 | ## Installation
|
| 25 |
|
| 26 | ```bash
|
| 27 | npm install @mojaloop/event-sdk
|
| 28 | ```
|
| 29 |
|
| 30 | ## Configuration
|
| 31 |
|
| 32 | Edit the file in `./config/default.json` to configure the logger, or set the following Environment variables:
|
| 33 |
|
| 34 | | Environment variable | Description | Default | Available Values |
|
| 35 | | --- | --- | --- | --- |
|
| 36 | | `EVENT_SDK_ASYNC_OVERRIDE_EVENTS` | A comma-separated list of events that should return immediately instead of waiting for the promises to resolve in the `recorder.record()` function. | `''` | Any combination of: `log,audit,trace` |
|
| 37 | |`EVENT_SDK_LOG_FILTER` | Comma deliminated List of `<eventType>`:`<eventAction>` key pairs that will be logged to the host console, as well as sent to the sidecar. Note `*:*` wildcard entry will print all logs, and if this field is empty ` ` then no logs will be printed. See [Current Supported Events](#current-supported-events) | `audit:*`, `log:info`, `log:error`, `log:warning` | `audit:*`, `log:info`, `log:error` |
|
| 38 | |`EVENT_SDK_LOG_METADATA_ONLY` | This flag will only print the metadata portion of the event message, and exclude the content to minimise log verbosity. | `false` | `true`, `false` |
|
| 39 | | `EVENT_SDK_SERVER_HOST` | The hostname for the gRPC server to bind to. | `localhost` | Any valid hostname |
|
| 40 | | `EVENT_SDK_SERVER_PORT` | The port for the gRPC server to listen on. | `50055` | Any valid port value |
|
| 41 | | `EVENT_SDK_SIDECAR_DISABLED` | Enables or disables the logging to event sidecar. | `true` | `true`, `false` |
|
| 42 | | ~~`EVENT_SDK_SIDECAR_WITH_LOGGER`~~ | _DEPRECATED BY `EVENT_SDK_LOG_FILTER`_ - If true, the events will be logged to the host console, as well as sent to the sidecar. Only applicable if the event sidecar is enabled. | `false` | `true`, `false` |
|
| 43 | | `EVENT_SDK_VENDOR_PREFIX` | Prefix for vendor specific tracestate handler. For more information refer [here](#tracestate-format-and-methods) | `acmevendor` | Any string |
|
| 44 | | `EVENT_SDK_TRACESTATE_HEADER_ENABLED` | If enabled, the tracestate value is kept updated with every child and is inserted into the span tags. Otherwise, the tracestate is only updated if `injectContextToHttpRequest` is called and the `tracestate` is included into the request headers. | `false` | `true`, `false` |
|
| 45 | | `EVENT_SDK_TRACEID_PER_VENDOR` | If enabled, when vendor of the parent span is different from the vendor set by `EVENT_SDK_VENDOR_PREFIX` the traceId will be new and the parent traceId will be stored as a tag: `corelationTraceId` . Otherwise, the traceId is persisted. | `false` | `true`, `false` |
|
| 46 |
|
| 47 | ## Tracestate format and methods
|
| 48 |
|
| 49 | _Note: Tags in the tracestate are supported from version [v9.4.1](https://github.com/mojaloop/event-sdk/releases/tag/v9.4.1). Since [v9.5.2](https://github.com/mojaloop/event-sdk/releases/tag/v9.5.2) tracestate is base64 encoded string. To be able to use the tracestate correctly accross all services, they should have same version of event-sdk and [central-services-shared](https://github.com/mojaloop/central-services-shared) librarires._
|
| 50 |
|
| 51 | ### Format
|
| 52 |
|
| 53 | Tracestate header can be used to preserve vendor specific information across various connected systems in multivendor setup. The format is according to the [w3c specifications](https://github.com/w3c/trace-context/blob/master/spec/20-http_header_format.md#tracestate-header).
|
| 54 | Tracestate header example value: `acmevendor=eyJzcGFuSWQiOiI2Njg2Nzk1MDBiMGUzYzQwIiwgInRyYW5zZmVyX3R4X21zOjE1OTA0MDc0NjUifQ==`, where the vendor is `acmevendor` and the value is base64 encoded key value pair as `spanId` key is set automatically. When decoded: `{"spanId":"668679500b0e3c40", "transfer_tx_ms:1590407465"}`
|
| 55 |
|
| 56 | ### Methods to access the tracestate are:
|
| 57 |
|
| 58 | * setTracestateTags - sets user tags into the tracestate
|
| 59 | * getTracestates - Returns the tracestates object per vendor, as configured vendor tracestate is decoded key value pair with tags
|
| 60 | * getTracestateTags - Returns the tracestate tags for the configured vendor as key value pairs
|
| 61 |
|
| 62 | ## Current Supported Events
|
| 63 |
|
| 64 | | eventType | eventAction | Description |
|
| 65 | | --- | --- | --- |
|
| 66 | | audit | default | Default audit action. Used when no action has been specified |
|
| 67 | | audit | start | Used to create start audit event |
|
| 68 | | audit | ingress | Used to create ingress audit event |
|
| 69 | | audit | egress | Used to create egress audit event |
|
| 70 | | audit | finish | Used to create finish audit event |
|
| 71 | | log | info | Info log level |
|
| 72 | | log | debug | Debug log level |
|
| 73 | | log | error | Error log level |
|
| 74 | | log | verbose | Verbose log level |
|
| 75 | | log | warning | Warning log level |
|
| 76 | | log | performance | Performance log level |
|
| 77 | | span | trace | Used to create trace event. These events sent with `span.finish()` method and are used for traceability |
|
| 78 |
|
| 79 | ## Usage
|
| 80 |
|
| 81 | Instrumented services should be part of a configuration which includes the [event sidecar](https://github.com/mojaloop/event-sidecar) and [event-streaming-processor](https://github.com/mojaloop/event-streaming-processor). Detailed architecture overview can be found [here](https://docs.mojaloop.io/documentation/mojaloop-technical-overview/event-framework/)
|
| 82 |
|
| 83 | Examples of usage of the SDK can be found in the `src/examples` directory of this repo: [Javascript example](src/examples/js_app.js) and [TypeScript example](src/examples/ts_app.ts).
|
| 84 |
|
| 85 | ## Auditing Dependencies
|
| 86 |
|
| 87 | We use `npm-audit-resolver` along with `npm audit` to check dependencies for vulnerabilities, and keep track of resolved dependencies with an `audit-resolv.json` file.
|
| 88 |
|
| 89 | To start a new resolution process, run:
|
| 90 |
|
| 91 | ```bash
|
| 92 | npm run audit:resolve
|
| 93 | ```
|
| 94 |
|
| 95 | You can then check to see if the CI will pass based on the current dependencies with:
|
| 96 |
|
| 97 | ```bash
|
| 98 | npm run audit:check
|
| 99 | ```
|
| 100 |
|
| 101 | And commit the changed `audit-resolv.json` to ensure that CircleCI will build correctly.
|
| 102 |
|
| 103 | ## Automated Releases
|
| 104 |
|
| 105 | As part of our CI/CD process, we use a combination of CircleCI, standard-version
|
| 106 | npm package and github-release CircleCI orb to automatically trigger our releases
|
| 107 | and image builds. This process essentially mimics a manual tag and release.
|
| 108 |
|
| 109 | On a merge to master, CircleCI is configured to use the mojaloopci github account
|
| 110 | to push the latest generated CHANGELOG and package version number.
|
| 111 |
|
| 112 | Once those changes are pushed, CircleCI will pull the updated master, tag and
|
| 113 | push a release triggering another subsequent build that also publishes a docker image.
|
| 114 |
|
| 115 | ### Potential problems
|
| 116 |
|
| 117 | * There is a case where the merge to master workflow will resolve successfully, triggering
|
| 118 | a release. Then that tagged release workflow subsequently failing due to the image scan,
|
| 119 | audit check, vulnerability check or other "live" checks.
|
| 120 |
|
| 121 | This will leave master without an associated published build. Fixes that require
|
| 122 | a new merge will essentially cause a skip in version number or require a clean up
|
| 123 | of the master branch to the commit before the CHANGELOG and bump.
|
| 124 |
|
| 125 | This may be resolved by relying solely on the previous checks of the
|
| 126 | merge to master workflow to assume that our tagged release is of sound quality.
|
| 127 | We are still mulling over this solution since catching bugs/vulnerabilities/etc earlier
|
| 128 | is a boon.
|
| 129 |
|
| 130 | * It is unknown if a race condition might occur with multiple merges with master in
|
| 131 | quick succession, but this is a suspected edge case.
|