14.1.1 • Published 1 year ago

@mojaloop/event-sdk v14.1.1

Weekly downloads
300
License
Apache-2.0
Repository
github
Last release
1 year ago

event-sdk

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:

RecorderBehaviour
DefaultLoggerRecorderLogs events to console
DefaultSidecarRecorderLogs events to sidecar synchronously
DefaultSidecarRecorderAsyncLogs 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.

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 variableDescriptionDefaultAvailable Values
EVENT_SDK_ASYNC_OVERRIDE_EVENTSA 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_FILTERComma delimited 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 Eventsaudit:*, log:info, log:error, log:warningaudit:*, log:info, log:error
EVENT_SDK_LOG_METADATA_ONLYThis flag will only print the metadata portion of the event message, and exclude the content to minimise log verbosity.falsetrue, false
EVENT_SDK_SERVER_HOSTThe hostname for the gRPC server to bind to.localhostAny valid hostname
EVENT_SDK_SERVER_PORTThe port for the gRPC server to listen on.50055Any valid port value
EVENT_SDK_SIDECAR_DISABLEDEnables or disables the logging to event sidecar.truetrue, false
EVENT_SDK_SIDECAR_WITH_LOGGERDEPRECATED 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.falsetrue, false
EVENT_SDK_VENDOR_PREFIXPrefix for vendor specific tracestate handler. For more information refer hereacmevendorAny string
EVENT_SDK_TRACESTATE_HEADER_ENABLEDIf 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.falsetrue, false
EVENT_SDK_TRACEID_PER_VENDORIf 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.falsetrue, false
EVENT_LOGGER_KAFKAWhen configured, events will be sent by default directly to Kafka. Should contain configuration for 3 Kafka producers in PRODUCER.EVENT.LOG, PRODUCER.EVENT.TRACE and PRODUCER.EVENT.AUDITundefinedundefined, {PRODUCER:...}
EVENT_LOGControls processing of log events. When undefined the default processing is used.undefinedundefined, sidecar, kafka, console, off
EVENT_TRACEControls processing of trace events. When undefined the default processing is used.undefinedundefined, sidecar, kafka, console, off
EVENT_AUDITControls processing of audit events. When undefined the default processing is used.undefinedundefined, sidecar, kafka, console, off

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

eventTypeeventActionDescription
auditdefaultDefault audit action. Used when no action has been specified
auditstartUsed to create start audit event
auditingressUsed to create ingress audit event
auditegressUsed to create egress audit event
auditfinishUsed to create finish audit event
loginfoInfo log level
logdebugDebug log level
logerrorError log level
logverboseVerbose log level
logwarningWarning log level
logperformancePerformance log level
spantraceUsed 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.

Auditing Dependencies

We use audit-ci along with npm audit to check dependencies for node vulnerabilities, and keep track of resolved dependencies with an audit-ci.jsonc file.

To start a new resolution process, run:

npm run audit:fix

You can then check to see if the CI will pass based on the current dependencies with:

npm run audit:check

The audit-ci.jsonc contains any audit-exceptions that cannot be fixed to ensure that CircleCI will build correctly.

Automated Releases

As part of our CI/CD process, we use a combination of CircleCI, standard-version npm package and github-release CircleCI orb to automatically trigger our releases and image builds. This process essentially mimics a manual tag and release.

On a merge to main, CircleCI is configured to use the mojaloopci github account to push the latest generated CHANGELOG and package version number.

Once those changes are pushed, CircleCI will pull the updated main, tag and push a release triggering another subsequent build that also publishes a docker image.

Potential problems

  • There is a case where the merge to main workflow will resolve successfully, triggering a release. Then that tagged release workflow subsequently failing due to the image scan, audit check, vulnerability check or other "live" checks.

    This will leave main without an associated published build. Fixes that require a new merge will essentially cause a skip in version number or require a clean up of the main branch to the commit before the CHANGELOG and bump.

    This may be resolved by relying solely on the previous checks of the merge to main workflow to assume that our tagged release is of sound quality. We are still mulling over this solution since catching bugs/vulnerabilities/etc earlier is a boon.

  • It is unknown if a race condition might occur with multiple merges with main in quick succession, but this is a suspected edge case.

14.1.0

1 year ago

14.1.1

1 year ago

14.0.2

1 year ago

14.0.1

1 year ago

12.0.0

2 years ago

12.0.1

2 years ago

12.0.2

2 years ago

14.0.0

2 years ago

13.0.0

2 years ago

11.0.2

3 years ago

11.0.0

3 years ago

11.0.1

3 years ago

10.7.2

3 years ago

10.7.1

4 years ago

10.7.0

4 years ago

10.6.0

5 years ago

10.4.0

5 years ago

9.5.2

5 years ago

9.5.1

5 years ago

9.5.0

5 years ago

9.4.1

5 years ago

9.4.0

5 years ago

9.3.0-snapshot

5 years ago

9.3.0

5 years ago

9.2.0

5 years ago

8.8.1-snapshot.3

5 years ago

8.8.1-snapshot.2

6 years ago

8.8.1-snapshot.1

6 years ago

8.8.0

6 years ago

8.8.0-snapshot.1

6 years ago

8.8.0-snapshot

6 years ago

8.7.0

6 years ago

8.6.2

6 years ago

8.6.1

6 years ago

8.3.1

6 years ago

8.6.0

6 years ago

8.3.0

6 years ago

8.1.0

6 years ago

7.4.6-snapshot

6 years ago

7.4.5-snapshot

6 years ago

7.4.4-snapshot

6 years ago

7.4.2-snapshot

6 years ago

7.4.1-snapshot

6 years ago

7.4.0

6 years ago

7.2.1

6 years ago

7.2.0

6 years ago

7.2.0-snapshot

6 years ago

7.1.0-snapshot

6 years ago

6.4.8-snapshot

6 years ago

6.4.7-snapshot

6 years ago

6.4.6-snapshot

6 years ago

6.4.5-snapshot

6 years ago

6.4.3-snapshot

6 years ago

6.4.2-snapshot

6 years ago

6.4.1-snapshot

6 years ago

6.4.0-snapshot

6 years ago

1.0.4-snapshot

6 years ago

1.0.3

6 years ago

0.0.1

6 years ago