telemetry-events-aws-dynamodb

Stability: 1 - Experimental

telemetry-events instrumentation for AWS SDK DynamoDB module.

Contributors

@tristanls

Contents

• Installation
• Usage
• Tests
• Documentation
• Releases

Installation

npm install telemetry-events-aws-dynamodb

Usage

To run the below example run:

npm run readme

"use strict";

const AWS = require("aws-sdk");
const events = require("events");
const LogTelemetryEvents = require("telemetry-events-log");
const pkg = require("../package.json");
const QuantifyTelemetryEvents = require("telemetry-events-quantify");
const TelemetryEvents = require("telemetry-events");

const instrument = require("../index.js");

const emitter = new events.EventEmitter();
const telemetryEmitter = new TelemetryEvents(
    {
        emitter: emitter,
        package: pkg
    }
);
const logs = new LogTelemetryEvents(
    {
        telemetry: telemetryEmitter
    }
);
const metrics = new QuantifyTelemetryEvents(
    {
        telemetry: telemetryEmitter
    }
);

let dynamodb = new AWS.DynamoDB(
{
    region: "us-east-1"
});

dynamodb = instrument(
    dynamodb,
    AWS.VERSION,
    [
        "getItem", "putItem", "deleteItem"
    ],
    {
        logs,
        metrics
    }
);

let documentClient = new AWS.DynamoDB.DocumentClient(
    {
        region: "us-east-1"
    }
);
documentClient = instrument.DocumentClient(
    documentClient,
    AWS.VERSION,
    [
        "createSet", "get"
    ],
    {
        logs,
        metrics
    }
);

console.log(typeof dynamodb.instrumentedGetItem);
// function
console.log(typeof dynamodb.instrumentedPutItem);
// function
console.log(typeof dynamodb.instrumentedDeleteItem);
// function

console.log(typeof documentClient.instrumentedCreateSet);
// function
console.log(typeof documentClient.instrumentedGet);
// function

Tests

npm test

Documentation

• instrument
• instrument.DocumentClient
• instrumentedMethod

instrument(dynamodb, version, methods, telemetry)

• dynamodb: Object Already created AWS.DynamoDB instance.
• version: String AWS module version (use AWS's VERSION parameter).
• methods: Array Array of methods to instrument.
• telemetry: Object Telemetry helpers.
  • logs: Object telemetry-events-log instance.
  • metrics: Object telemetry-events-quantify instance.
• Return: Object AWS.DynamoDB instance with additional instrumented methods.

For every specified method in methods creates an instrumented variant on the passed in dynamodb instance. For example, if methods = ["getItem"], the returned dynamodb object will have a dynamodb.instrumentedGetItem method.

instrument.DocumentClient(client, version, methods, telemetry)

• client: Object Already created AWS.DynamoDB.DocumentClient instance.
• version: String AWS module version (use AWS's VERSION parameter).
• methods: Array Array of methods to instrument.
• telemetry: Object Telemetry helpers.
  • logs: Object telemetry-events-log instance.
  • metrics: Object telemetry-events-quantify instance.
• Return: Object AWS.DynamoDB.DocumentClient instance with additional instrumented methods.

For every specified method in methods creates an instrumented variant on the passed in client instance. For example, if methods = ["get"], the returned client object will have a client.instrumentedGet method.

instrumentedMethod(params, context, callback)

• params: Object Parameters to call the instrumented method with.
• context Object Call context.
  • metadata: Object (Default: undefined) Metadata to include in events.
  • parentSpan: Object (Default: undefined) telemetry-events-tracing parent span to create a child tracing span from.
  • paramsToLog: Object (Default: params) Parameters to log instead of params.
• callback: Function function (error, data, context){} Callback that will be called with the results of the instrumented method.
  • error: Error Error from instrumented method result, if any.
  • data: Object Data form instrumented method result, if any.
  • context: Object Result context containing target (instrumented method) metadata.
    • targetMetadata: Object Target (instrumented method) metadata.

This is an example of an instrumented method signature (actual method names would be instrumentedGetItem, instrumentedPutItem, etc.).

Releases

We follow semantic versioning policy (see: semver.org):

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.