README
event-sdk
EXPERIMENTAL Event SDK for Clients & Server implementations
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.
The API is defined by the EventRecorder
interface and the EventMessage
type.
This library provides the following recorder implementations by default:
| Recorder | Behaviour |
| - | - |
| DefaultLoggerRecorder
| Logs events to console |
| DefaultSidecarRecorder
| Logs events to sidecar synchronously |
| DefaultSidecarRecorderAsync
| Logs events to sidecar asynchronously |
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.
Installation
npm install @mojaloop/event-sdk
Configuration
Edit the file in ./config/default.json
to configure the logger, or set the following Environment variables:
Environment variable | Description | Default | Available Values |
---|---|---|---|
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 |
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 |
audit:* , log:info , log:error , log:warning |
audit:* , log:info , log:error |
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 |
EVENT_SDK_SERVER_HOST |
The hostname for the gRPC server to bind to. | localhost |
Any valid hostname |
EVENT_SDK_SERVER_PORT |
The port for the gRPC server to listen on. | 50055 |
Any valid port value |
EVENT_SDK_SIDECAR_DISABLED |
Enables or disables the logging to event sidecar. | true |
true , false |
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 |
EVENT_SDK_VENDOR_PREFIX |
Prefix for vendor specific tracestate handler. For more information refer here | acmevendor |
Any string |
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 |
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 |
Tracestate format and methods
Note: Tags in the tracestate are supported from version v9.4.1. Since 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 librarires.
Format
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.
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"}
Methods to access the tracestate are:
- setTracestateTags - sets user tags into the tracestate
- getTracestates - Returns the tracestates object per vendor, as configured vendor tracestate is decoded key value pair with tags
- getTracestateTags - Returns the tracestate tags for the configured vendor as key value pairs
Current Supported Events
eventType | eventAction | Description |
---|---|---|
audit | default | Default audit action. Used when no action has been specified |
audit | start | Used to create start audit event |
audit | ingress | Used to create ingress audit event |
audit | egress | Used to create egress audit event |
audit | finish | Used to create finish audit event |
log | info | Info log level |
log | debug | Debug log level |
log | error | Error log level |
log | verbose | Verbose log level |
log | warning | Warning log level |
log | performance | Performance log level |
span | trace | Used to create trace event. These events sent with span.finish() method and are used for traceability |
Usage
Instrumented services should be part of a configuration which includes the event sidecar and event-streaming-processor. Detailed architecture overview can be found here
Examples of usage of the SDK can be found in the src/examples
directory of this repo: Javascript example and TypeScript example.