Tracing the easy way using JSON.

Overview

MikroTrace

Tracing the easy way using JSON.

Build Status

Quality Gate Status

codecov

Maintainability


JSON tracer that tries to emulate OpenTelemetry semantics and behavior. Built as a ligher-weight way to handle spans in technical contexts like AWS Lambda to Honeycomb.

My rationale to build and distribute this is because setting up OpenTelemetry (OTEL) was harder than I would have wanted and expected. Also, while some of the semantics are nice, my feeling was that generally it was not the DX that I was hoping for. I can see a lot of developers fall through on their tracing journey going this route... MikroTrace attempts to simplify and minimize how traces are created. It is specially built for those cases in which you can use JSON logs and have your observability tool translate these into traces in that system.

So what do you get with MikroTrace?

  • Tracing that just works!
  • Familiar OTEL-type semantics
  • Works perfectly with AWS and Honeycomb
  • It removes the need to pass in complete instances into the span functions, instead use plain strings to refer to spans
  • Uses process.stdout.write() rather than console.log() so you can safely use it in Lambda
  • Tiny (~2 KB gzipped)
  • Has zero dependencies
  • Has 100% test coverage

Behavior

When you run MikroTrace.start({ ...your input }) with input, this will override any previously set configuration. When run without input, i.e. MikroTrace.start(), you can reuse the same instance again, making it easier to use across an application without having to pass the instance around. Make sure to end any spans before doing this.

MikroTrace will set the parent context automatically but you can override this. See the below Usage section for more on this.

MikroTrace only supports a single tracing context. Use the MikroTrace.start() functionality to get a new clean slate if needed.

Usage

Basic importing and usage

// ES5 format
const { MikroTrace } = require('mikrotrace');
// ES6 format
import { MikroTrace } from 'mikrotrace';

const tracer = MikroTrace.start({ serviceName: 'My service' });

Create nested span

const tracer = MikroTrace.start({ serviceName: 'My service' });

const span = tracer.start('My span');
const innerSpan = tracer.start('My inner span');
innerSpan.end();
span.end();

End all spans at once

const tracer = MikroTrace.start({ serviceName: 'My service' });

tracer.start('My span');
tracer.start('My extra span');
tracer.endAll();

Set a single attribute

const tracer = MikroTrace.start({ serviceName: 'My service' });

const span = tracer.start('My span');
span.setAttribute('key', 'some value');

Set multiple attributes

const tracer = MikroTrace.start({ serviceName: 'My service' });

const span = tracer.start('My span');
span.setAttributes({ something: 'my thing here', abc: 123 });

Get the configuration of a span

const tracer = MikroTrace.start({ serviceName: 'My service' });

const span = tracer.start('My span');
const config = span.getConfiguration();

Configuration

Set the correlation ID for the tracer at start

const tracer = MikroTrace.start({ correlationId: 'abc-123', serviceName: 'My service' });

Set the correlation ID for the tracer after instantiation

const tracer = MikroTrace.start({ serviceName: 'My service' });
tracer.setCorrelationId('abc-123');

Set the parent context manually

const tracer = MikroTrace.start({ serviceName: 'My service' });

const span = tracer.start('My span');
tracer.setParentContext('Some other context');
span.end();

Enrich the tracer with correlation ID, service name, or parent context without creating a new instance

const tracer = MikroTrace.enrich({
  serviceName: 'My new service',
  correlationId: 'qwerty-137',
  parentContext: 'some-other-parent'
});

Output the tracer configuration, for example for debugging purposes

const tracer = MikroTrace.start({ serviceName: 'My service' });
const tracerConfig = tracer.getConfiguration();

Demo

// Import
import { MikroTrace } from './src/entities/MikroTrace';

/**
 * Ideally have a configuration object or file that contains all
 * needed span names to make it easier to reference them.
 */
const spanNames = {
  outerSpan: 'I am the outer span',
  innerSpan: 'I am inside of the outer span',
  nestedInnerSpan: 'I am hidden deep inside'
};

/**
 * The tracer instance that you will reuse in your application.
 * The correlation ID is not required but is _highly_ recommended.
 */
const tracer = MikroTrace.start({ serviceName: 'MyService', correlationId: 'your-correlation-id' });
/**
 * You may also set the correlation ID after instantiation:
 * @example tracer.setCorrelationId('your-correlation-id');
 */

/**
 * Each time you call `tracer.start()` a new span is created.
 * All it takes is a unique span name.
 */
const span = tracer.start(spanNames['outerSpan']);

/**
 * Here we are creating an inner span. No magic: The tracer will
 * assume that the first trace is the parent.
 */
const innerSpan = tracer.start(spanNames['innerSpan']);

/**
 * If this is not the case and you need to assign another parent span,
 * they you can do it by adding the parent span in the second argument:
 */
const innermostSpan = tracer.start(spanNames['nestedInnerSpan'], spanNames['innerSpan']);

/**
 * We call `span.end()` to close the span(s) and print the log(s) for each trace.
 */
innermostSpan.end();
innerSpan.end();
span.end();

/*
EXAMPLE OUTPUT BELOW

const outputInnerSpan = {
  name: 'Call the User service and fetch a response',
  timestamp: '2022-06-26T16:11:41.977Z',
  timestampEpoch: '1656252701000',
  durationMs: 0,
  spanName: 'Call the User service and fetch a response',
  spanParentId: '5dec9b5a-acda-4cdf-924f-f8cf6df236c2',
  spanId: 'd3a06fab-8f81-45c9-bcd8-e458e62a3ef9',
  traceId: 'db62951b-d9a5-4fb6-adf0-10c360e6535f',
  attributes: {},
  correlationId: 'your-correlation-id',
  service: 'MyService',
  isEnded: true
};

const outputOuterSpan = {
  name: 'Greet a user',
  timestamp: '2022-06-26T16:11:41.977Z',
  timestampEpoch: '1656252701000',
  durationMs: 1,
  spanName: 'Greet a user',
  spanId: '5dec9b5a-acda-4cdf-924f-f8cf6df236c2',
  traceId: 'db62951b-d9a5-4fb6-adf0-10c360e6535f',
  attributes: {},
  correlationId: 'your-correlation-id',
  service: 'MyService',
  isEnded: true
};
*/
You might also like...

✏️ A small jQuery extension to turn a static HTML table into an editable one. For quickly populating a small table with JSON data, letting the user modify it with validation, and then getting JSON data back out.

jquery-editable-table A small jQuery extension to turn an HTML table editable for fast data entry and validation Demo 👉 https://jsfiddle.net/torrobin

Jul 31, 2022

Add aliasing support to Vite from tsconfig.json or jsconfig.json files

Config to Alias Config to Alias adds aliasing support to Astro, JavaScript, TypeScript, and CSS files. Usage Install Config to Alias. npm install @ast

Mar 17, 2023

A minimalistic yet efficient way to stringify and revive instances via JSON.

json-instances Social Media Photo by Francisco J. Villena on Unsplash A minimalistic yet efficient way to stringify and revive instances via JSON. If

Jun 23, 2022

🎨 Beautify your github profile with this amazing tool, creating the readme your way in a simple and fast way 🚀 The best profile readme generator you will find ⚡

🎨 Beautify your github profile with this amazing tool, creating the readme your way in a simple and fast way 🚀 The best profile readme generator you will find ⚡

Demo Profile Readme Generator The best profile readme generator you will find! About | Technologies | Requirements | Starting | Contributing 🎯 About

Jan 1, 2023

A NodeJS Replit API package wrapped around GraphQL, returning JSON data for easy use.

repl-api.js A NodeJS Replit API package wrapped around GraphQL, returning JSON data for easy use. Contents: About Quickstart Pre-installation Installa

May 20, 2022

A simple, easy to use and extendible JSON database.

A simple, easy to use and extendible JSON database.

Newton ⚠️ This package is under active development: Compatibility and APIs may change. A simple, easy to use and extendible JSON database. Table of co

Dec 6, 2022

Easy server-side and client-side validation for FormData, URLSearchParams and JSON data in your Fresh app 🍋

Fresh Validation 🍋     Easily validate FormData, URLSearchParams and JSON data in your Fresh app server-side or client-side! Validation Fresh Validat

Dec 23, 2022

A high-resolution local database that uses precise algorithms to easily record data in local files within a project with persistent JSON and YAML support designed to be easy to set up and use

A high-resolution local database that uses precise algorithms to easily record data in local files within a project with persistent JSON and YAML support designed to be easy to set up and use

About A high-resolution local database that uses precise algorithms to easily record data in local files within a project with persistent JSON and YML

Dec 28, 2022

🛠 Nodejs configuration the easy way.

@elite-libs/auto-config Intro A Unified Config & Arguments Library for Node.js! Featuring support for environment variables, command line arguments, a

May 17, 2022
Releases(v2.0.4)
  • v2.0.4(Nov 15, 2022)

    What's Changed

    • fix(): spread dynamic metadata before static metadata

    Full Changelog: https://github.com/mikaelvesavuori/mikrotrace/compare/v2.0.3...v2.0.4

    Source code(tar.gz)
    Source code(zip)
  • v2.0.3(Nov 14, 2022)

    What's Changed

    • Add support for custom static metadata
    • Update docs
    • Bump version
    • Add tests
    • Update SECURITY

    Full Changelog: https://github.com/mikaelvesavuori/mikrotrace/compare/v2.0.2...v2.0.3

    Source code(tar.gz)
    Source code(zip)
  • v2.0.2(Nov 14, 2022)

    What's Changed

    • Add filtering of empties in resulting log/trace
    • Remove name from output
    • Ensure correlationId is picked up from metadata if present
    • Update reference to size of package

    Full Changelog: https://github.com/mikaelvesavuori/mikrotrace/compare/v2.0.1...v2.0.2

    Source code(tar.gz)
    Source code(zip)
  • v2.0.1(Nov 14, 2022)

    What's Changed

    • Add aws-metadata-utils instead of doing it in MikroTrace
    • Add test for resetting instance metadata
    • Add test data
    • Add AWS metadata support

    Full Changelog: https://github.com/mikaelvesavuori/mikrotrace/compare/v2.0.0...v2.0.1

    Source code(tar.gz)
    Source code(zip)
  • v2.0.0(Jul 25, 2022)

    What's Changed

    • Use singleton implementation that works same as MikroLog
    • Update API as per above
    • Update docs to reflect changes and additions
    • Add tests and updates to reflect changes

    Full Changelog: https://github.com/mikaelvesavuori/mikrotrace/compare/v1.1.0...v2.0.0

    Source code(tar.gz)
    Source code(zip)
  • v1.1.0(Jul 25, 2022)

    What's Changed

    • Sync timestamp formats between MikroTrace and MikroLog using timestamp (ISO/RFC format) and timestampEpoch (Unix format) fields
    • Remove useless endTime field

    Full Changelog: https://github.com/mikaelvesavuori/mikrotrace/compare/v1.0.0...v1.1.0

    Source code(tar.gz)
    Source code(zip)
  • v1.0.0(Jul 13, 2022)

Owner
Mikael Vesavuori
Cloud Software Architect + Technical Standards Lead at Polestar
Mikael Vesavuori
JCS (JSON Canonicalization Scheme), JSON digests, and JSON Merkle hashes

JSON Hash This package contains the following JSON utilties for Deno: digest.ts provides cryptographic hash digests of JSON trees. It guarantee that d

Hong Minhee (洪 民憙) 13 Sep 2, 2022
Package fetcher is a bot messenger which gather npm packages by uploading either a json file (package.json) or a picture representing package.json. To continue...

package-fetcher Ce projet contient un boilerplate pour un bot messenger et l'executable Windows ngrok qui va permettre de créer un tunnel https pour c

AILI Fida Aliotti Christino 2 Mar 29, 2022
Catalogist is the easy way to catalog and make your software and (micro)services visible to your organization in a lightweight and developer-friendly way.

catalogist ?? ?? ?? ?? ?? The easy way to catalog and make your software and (micro)services visible to your organization through an API You were a pe

Mikael Vesavuori 11 Dec 13, 2022
An easy and simply way to create your own image classifier AI using ml5.js and Google's Teachable Machine

An easy and simply way to create your own image classifier AI using ml5.js and Google's Teachable Machine

Mateus Vinícius de Lima 2 Apr 5, 2022
Json-parser - A parser for json-objects without dependencies

Json Parser This is a experimental tool that I create for educational purposes, it's based in the jq works With this tool you can parse json-like stri

Gabriel Guerra 1 Jan 3, 2022
Pretty-print-json - 🦋 Pretty-print JSON data into HTML to indent and colorize (written in TypeScript)

pretty-print-json Pretty-print JSON data into HTML to indent and colorize (written in TypeScript) 1) Try It Out Interactive online tool to format JSON

Center Key 87 Dec 30, 2022
JSON Visio is data visualization tool for your json data which seamlessly illustrates your data on graphs without having to restructure anything, paste directly or import file.

JSON Visio is data visualization tool for your json data which seamlessly illustrates your data on graphs without having to restructure anything, paste directly or import file.

Aykut Saraç 20.6k Jan 4, 2023
JSON Struct is a vocabulary that allows you to annotate and validate JSON documents.

JSON-Struct JSON Struct is a vocabulary that allows you to annotate and validate JSON documents. Examples Basic This is a simple example of vocabulary

Saman 3 May 8, 2022
Prisma 2+ generator to emit a JSON file that can be run with json-server

Prisma JSON Server Generator A Prisma generator that automates creating a JSON file that can be run as a server from your Prisma schema. Explore the o

Omar Dulaimi 14 Jan 7, 2023
Types generator will help user to create TS types from JSON. Just paste your single object JSON the Types generator will auto-generate the interfaces for you. You can give a name for the root object

Types generator Types generator is a utility tool that will help User to create TS Interfaces from JSON. All you have to do is paste your single objec

Vineeth.TR 16 Dec 6, 2022