Wondering what’s next for npm?Check out our public roadmap! »

@mojaloop/event-sdkTypeScript icon, indicating that this package has built-in type declarations

10.6.0 • Public • Published


EXPERIMENTAL Event SDK for Clients & Server implementations

Git Commit Git Releases Npm Version NPM Vulnerabilities CircleCI

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 EventMessages before sending them and its response, respectively.


npm install @mojaloop/event-sdk


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.


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


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.



npm i @mojaloop/event-sdk

DownloadsWeekly Downloads






Unpacked Size

274 kB

Total Files


Last publish


  • avatar
  • avatar
  • avatar
  • avatar