feat(context): create trace context class

Author: Stephen Belanger

lib/instrumentation/context.js

@@ -0,0 +1,87 @@
+const crypto = require('crypto')
+
+function fromHex (hex) {
+  return Buffer.from(hex, 'hex')
+}
+
+function toHex (buffer) {
+  return buffer.toString('hex')
+}
+
+class TraceContext {
+  constructor (opts = {}) {
+    // 1 byte
+    this.version = opts.version
+    // 16 bytes
+    this.traceId = opts.traceId
+    // 8 bytes
+    this.id = opts.id
+    // 1 byte
+    this.flags = opts.flags
+    // 8 bytes
+    this.parentId = opts.parentId
+  }
+
+  static create () {
+    const bytes = crypto.randomBytes(24)
+
+    return new TraceContext({
+      version: Buffer.alloc(1),
+      traceId: bytes.slice(0, 16),
+      id: bytes.slice(16),
+      flags: Buffer.alloc(1)
+    })
+  }
+
+  static fromString (header) {
+    const [
+      version,
+      traceId,
+      id,
+      flags
+    ] = header.split('-').map(fromHex)
+
+    return new TraceContext({
+      version,
+      traceId,
+      id,
+      flags
+    })
+  }
+
+  child () {
+    const { version, traceId, id: parentId, flags } = this
+    const id = crypto.randomBytes(8)
+
+    return new TraceContext({
+      version,
+      traceId,
+      id,
+      flags,
+      parentId
+    })
+  }
+
+  toString () {
+    const parts = [
+      this.version,
+      this.traceId,
+      this.id,
+      this.flags
+    ]
+
+    return parts.map(toHex).join('-')
+  }
+
+  toJSON () {
+    return {
+      version: this.version.toString('hex'),
+      traceId: this.traceId.toString('hex'),
+      id: this.id.toString('hex'),
+      flags: this.flags.toString('hex'),
+      parentId: this.parentId && this.parentId.toString('hex')
+    }
+  }
+}
+
+module.exports = TraceContext

test/instrumentation/context.js

@@ -0,0 +1,88 @@
+'use strict'
+
+const crypto = require('crypto')
+const test = require('tape')
+
+const TraceContext = require('../../lib/instrumentation/context')
+
+const version = Buffer.alloc(1)
+const traceId = crypto.randomBytes(16)
+const id = crypto.randomBytes(8)
+const flags = Buffer.alloc(1)
+
+const header = `00-${traceId.toString('hex')}-${id.toString('hex')}-00`
+
+test('constructor', t => {
+  const context = new TraceContext({
+    version,
+    traceId,
+    id,
+    flags
+  })
+
+  t.ok(context instanceof TraceContext, 'has a trace context object')
+  t.ok(version.equals(context.version), 'version matches')
+  t.ok(traceId.equals(context.traceId), 'traceId matches')
+  t.ok(id.equals(context.id), 'id matches')
+  t.ok(flags.equals(context.flags), 'flags matches')
+
+  t.end()
+})
+
+test('fromString', t => {
+  const context = TraceContext.fromString(header)
+
+  t.ok(context instanceof TraceContext, 'has a trace context object')
+  t.ok(version.equals(context.version), 'version matches')
+  t.ok(traceId.equals(context.traceId), 'traceId matches')
+  t.ok(id.equals(context.id), 'id matches')
+  t.ok(flags.equals(context.flags), 'flags matches')
+
+  t.end()
+})
+
+test('toString', t => {
+  const result = TraceContext.fromString(header).toString()
+  t.equal(result, header, 'trace context stringifies to valid header')
+  t.end()
+})
+
+test('toJSON', t => {
+  const context = TraceContext.fromString(header)
+
+  t.deepEqual(context.toJSON(), {
+    version: version.toString('hex'),
+    traceId: traceId.toString('hex'),
+    id: id.toString('hex'),
+    flags: flags.toString('hex'),
+    parentId: undefined
+  }, 'trace context serializes fields to hex strings, in JSON form')
+
+  t.end()
+})
+
+test('create', t => {
+  const context = TraceContext.create()
+
+  t.ok(context instanceof TraceContext, 'has a trace context object')
+  t.ok(version.equals(context.version), 'version matches')
+  t.notOk(traceId.equals(context.traceId), 'has new traceId')
+  t.notOk(id.equals(context.id), 'has new spanId')
+  t.ok(flags.equals(context.flags), 'flags matches')
+
+  t.end()
+})
+
+test('child', t => {
+  const parent = TraceContext.fromString(header)
+  const context = parent.child()
+
+  t.ok(context instanceof TraceContext, 'has a trace context object')
+  t.ok(version.equals(context.version), 'version matches')
+  t.ok(traceId.equals(context.traceId), 'traceId matches')
+  t.notOk(id.equals(context.id), 'has new id')
+  t.ok(flags.equals(context.flags), 'flags matches')
+  t.ok(parent.id.equals(context.parentId), 'parentId matches parent.id')
+
+  t.end()
+})