Skip to content

Commit

Permalink
refactor: clean up types slightly (drop GenericSpan, s/agent/apm/ per…
Browse files Browse the repository at this point in the history 
… docs (#2300)

- Drop the "GenericSpan" interface in our types. It isn't an external
  concept and there wasn't a lot of utility in using inheritance for it
  in the types file.
- Change from 'agent.' to 'apm.' usage in the types test file because
  'apm' is the prefix we encourage in docs (for good reason I think, it
  is less ambiguous).
  • Loading branch information
@trentm
trentm authored Aug 25, 2021
1 parent a632b79 commit e1a9a79
Show file tree
Hide file tree
Showing 3 changed files with 125 additions and 122 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
/package-lock.json
/test/babel/out.js
/test/types/transpile/index.js
/test/types/transpile-default/index.js
/test-suite-output.tap

# Folders to ignore
Expand Down
46 changes: 24 additions & 22 deletions index.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,31 +127,27 @@ declare namespace apm {
setSpanOutcome(outcome: Outcome): void;
}

type Outcome = 'unknown' | 'success' | 'failure'
type Outcome = 'unknown' | 'success' | 'failure';

interface GenericSpan {
// Transaction API
// https://www.elastic.co/guide/en/apm/agent/nodejs/current/transaction-api.html
export interface Transaction {
// The following properties and methods are currently not documented as their API isn't considered official:
// timestamp, ended, id, traceId, parentId, sampled, duration()
// - timestamp, ended, id, traceId, parentId, sampled, duration()
// - setUserContext(), setCustomContext(), toJSON(), setDefaultName(), setDefaultNameFromRequest()

name: string;
type: string | null;
subtype: string | null;
action: string | null;
traceparent: string;
outcome: Outcome;
result: string | number;

setType (type?: string | null, subtype?: string | null, action?: string | null): void;
setLabel (name: string, value: LabelValue, stringify?: boolean): boolean;
addLabels (labels: Labels, stringify?: boolean): boolean;
}

// Transaction API
// https://www.elastic.co/guide/en/apm/agent/nodejs/current/transaction-api.html
export interface Transaction extends GenericSpan {
// The following properties and methods are currently not documented as their API isn't considered official:
// setUserContext(), setCustomContext(), toJSON(), setDefaultName(), setDefaultNameFromRequest()

name: string;
result: string | number;
setOutcome(outcome: Outcome): void;

startSpan(
name?: string | null,
Expand All @@ -177,22 +173,28 @@ declare namespace apm {
): Span | null;
ensureParentId (): string;
end (result?: string | number | null, endTime?: number): void;

setOutcome(outcome: Outcome): void;
}

// Span API
// https://www.elastic.co/guide/en/apm/agent/nodejs/current/span-api.html
export interface Span extends GenericSpan {
export interface Span {
// The following properties and methods are currently not documented as their API isn't considered official:
// customStackTrace(), setDbContext()
// - timestamp, ended, id, traceId, parentId, sampled, duration()
// - customStackTrace(), setDbContext()

transaction: Transaction;
name: string;
type: string | null;
subtype: string | null;
action: string | null;
traceparent: string;
outcome: Outcome;

end (endTime?: number): void;

setType (type?: string | null, subtype?: string | null, action?: string | null): void;
setLabel (name: string, value: LabelValue, stringify?: boolean): boolean;
addLabels (labels: Labels, stringify?: boolean): boolean;
setOutcome(outcome: Outcome): void;
end (endTime?: number): void;
}

// https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html
Expand Down Expand Up @@ -330,10 +332,10 @@ declare namespace apm {
type PatchHandler = (exports: any, agent: Agent, options: PatchOptions) => any;

interface PatchOptions {
version: string | undefined,
enabled: boolean
version: string | undefined;
enabled: boolean;
}
}

declare const apm: apm.Agent;
export = apm
export = apm;
200 changes: 100 additions & 100 deletions test/types/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
// Note: This test file is the one intended to *fully* exercise the exported
// types. Any types changes should result in an update to this file.

import agent, {
import apm, {
AgentConfigOptions,
Transaction,
Span,
Expand All @@ -17,104 +17,104 @@ const agentOpts: AgentConfigOptions = {
metricsInterval: '0',
centralConfig: false
}
agent.start(agentOpts)
apm.start(agentOpts)

function started (aBool: boolean) {
console.log(`aBool is: ${aBool}`)
}
started(agent.isStarted())
started(apm.isStarted())

const trans = agent.currentTransaction
const trans = apm.currentTransaction
if (trans) trans.end()
const span = agent.currentSpan
const span = apm.currentSpan
if (span) span.end()
const traceparent = agent.currentTraceparent
const traceparent = apm.currentTraceparent
if (traceparent) traceparent.split('-')
const currentTraceIds = agent.currentTraceIds
const currentTraceIds = apm.currentTraceIds
let traceId = currentTraceIds['trace.id'] || ''
traceId += '-' + (currentTraceIds['transaction.id'] === undefined
? currentTraceIds['transaction.id']
: currentTraceIds['span.id'])

agent.setFramework({})
agent.setFramework({ name: 'foo' })
agent.setFramework({ name: 'foo', version: 'bar' })
agent.setFramework({ version: 'bar' })
agent.setFramework({ name: 'foo', version: 'bar', overwrite: false })
apm.setFramework({})
apm.setFramework({ name: 'foo' })
apm.setFramework({ name: 'foo', version: 'bar' })
apm.setFramework({ version: 'bar' })
apm.setFramework({ name: 'foo', version: 'bar', overwrite: false })

agent.addPatch('foo', 'bar')
agent.addPatch(['foo'], 'bar')
agent.addPatch('foo', function (exports, agent, options) {
apm.addPatch('foo', 'bar')
apm.addPatch(['foo'], 'bar')
apm.addPatch('foo', function (exports, agent, options) {
agent.isStarted()
if (options.enabled) {}
})
agent.removePatch('foo', 'bar')
agent.removePatch(['foo'], 'bar')
agent.clearPatches('foo')
agent.clearPatches(['foo'])
apm.removePatch('foo', 'bar')
apm.removePatch(['foo'], 'bar')
apm.clearPatches('foo')
apm.clearPatches(['foo'])

agent.lambda(() => {})
agent.lambda('foo', () => {})
apm.lambda(() => {})
apm.lambda('foo', () => {})

agent.handleUncaughtExceptions()
agent.handleUncaughtExceptions((err: Error) => {
apm.handleUncaughtExceptions()
apm.handleUncaughtExceptions((err: Error) => {
console.error(err.stack)
process.exit(1)
})

agent.captureError(new Error('foo'))
agent.captureError('foo')
agent.captureError({ message: 'hello %s', params: ['world'] })
agent.captureError(new Error('foo'), { tags: { foo: 'bar' } })
agent.captureError('foo', { tags: { foo: 'bar' } })
agent.captureError({ message: 'hello %s', params: ['world'] }, { tags: { foo: 'bar' } })
agent.captureError(new Error('foo'), { tags: { foo: 'bar' } }, () => {})
agent.captureError('foo', { tags: { foo: 'bar' } }, () => {})
agent.captureError({ message: 'hello %s', params: ['world'] }, { tags: { foo: 'bar' } }, () => {})
agent.captureError(new Error('foo'), () => {})
agent.captureError('foo', () => {})
agent.captureError({ message: 'hello %s', params: ['world'] }, () => {})

agent.startTransaction()
agent.startTransaction('foo')
agent.startTransaction('foo', 'type')
agent.startTransaction('foo', 'type', 'subtype')
agent.startTransaction('foo', 'type', 'subtype', 'action')
agent.startTransaction('foo', { startTime: 1 })
agent.startTransaction('foo', 'type', { startTime: 1 })
agent.startTransaction('foo', 'type', 'subtype', { startTime: 1 })
agent.startTransaction('foo', 'type', 'subtype', 'action', { startTime: 1 })

agent.setTransactionName('foo')

agent.endTransaction()

agent.startSpan()
agent.startSpan('foo')
agent.startSpan('foo', 'type')
agent.startSpan('foo', 'type', 'subtype')
agent.startSpan('foo', 'type', 'subtype', 'action')
agent.startSpan('foo', { childOf: 'baz' })
agent.startSpan('foo', 'type', { childOf: 'baz' })
agent.startSpan('foo', 'type', 'subtype', { childOf: 'baz' })
agent.startSpan('foo', 'type', 'subtype', 'action', { childOf: 'baz' })

agent.setLabel('foo', 'bar')
agent.setLabel('foo', 1)
agent.setLabel('foo', false)
agent.setLabel('foo', 1, false)
agent.setLabel('foo', false, false)

agent.addLabels({ s: 'bar', n: 42, b: false })
agent.addLabels({ s: 'bar', n: 42, b: false }, false)

agent.setUserContext({
apm.captureError(new Error('foo'))
apm.captureError('foo')
apm.captureError({ message: 'hello %s', params: ['world'] })
apm.captureError(new Error('foo'), { tags: { foo: 'bar' } })
apm.captureError('foo', { tags: { foo: 'bar' } })
apm.captureError({ message: 'hello %s', params: ['world'] }, { tags: { foo: 'bar' } })
apm.captureError(new Error('foo'), { tags: { foo: 'bar' } }, () => {})
apm.captureError('foo', { tags: { foo: 'bar' } }, () => {})
apm.captureError({ message: 'hello %s', params: ['world'] }, { tags: { foo: 'bar' } }, () => {})
apm.captureError(new Error('foo'), () => {})
apm.captureError('foo', () => {})
apm.captureError({ message: 'hello %s', params: ['world'] }, () => {})

apm.startTransaction()
apm.startTransaction('foo')
apm.startTransaction('foo', 'type')
apm.startTransaction('foo', 'type', 'subtype')
apm.startTransaction('foo', 'type', 'subtype', 'action')
apm.startTransaction('foo', { startTime: 1 })
apm.startTransaction('foo', 'type', { startTime: 1 })
apm.startTransaction('foo', 'type', 'subtype', { startTime: 1 })
apm.startTransaction('foo', 'type', 'subtype', 'action', { startTime: 1 })

apm.setTransactionName('foo')

apm.endTransaction()

apm.startSpan()
apm.startSpan('foo')
apm.startSpan('foo', 'type')
apm.startSpan('foo', 'type', 'subtype')
apm.startSpan('foo', 'type', 'subtype', 'action')
apm.startSpan('foo', { childOf: 'baz' })
apm.startSpan('foo', 'type', { childOf: 'baz' })
apm.startSpan('foo', 'type', 'subtype', { childOf: 'baz' })
apm.startSpan('foo', 'type', 'subtype', 'action', { childOf: 'baz' })

apm.setLabel('foo', 'bar')
apm.setLabel('foo', 1)
apm.setLabel('foo', false)
apm.setLabel('foo', 1, false)
apm.setLabel('foo', false, false)

apm.addLabels({ s: 'bar', n: 42, b: false })
apm.addLabels({ s: 'bar', n: 42, b: false }, false)

apm.setUserContext({
id: 'foo',
username: 'bar',
email: 'baz'
})

agent.setCustomContext({ foo: { bar: { baz: true } } })
apm.setCustomContext({ foo: { bar: { baz: true } } })

function filter1 (payload: any) {
payload.foo = 'bar'
Expand All @@ -124,36 +124,36 @@ function filter2 (payload: any) {
return false
}
function filter3 (payload: any) {}
agent.addFilter(filter1)
agent.addFilter(filter2)
agent.addFilter(filter3)
agent.addErrorFilter(filter1)
agent.addErrorFilter(filter2)
agent.addErrorFilter(filter3)
agent.addTransactionFilter(filter1)
agent.addTransactionFilter(filter2)
agent.addTransactionFilter(filter3)
agent.addSpanFilter(filter1)
agent.addSpanFilter(filter2)
agent.addSpanFilter(filter3)
agent.addMetadataFilter(filter1)
agent.addMetadataFilter(filter2)
agent.addMetadataFilter(filter3)

agent.flush()
agent.flush(() => {})

agent.destroy()

agent.logger.trace('')
agent.logger.debug('')
agent.logger.info('')
agent.logger.warn('')
agent.logger.error('')
agent.logger.fatal('')
apm.addFilter(filter1)
apm.addFilter(filter2)
apm.addFilter(filter3)
apm.addErrorFilter(filter1)
apm.addErrorFilter(filter2)
apm.addErrorFilter(filter3)
apm.addTransactionFilter(filter1)
apm.addTransactionFilter(filter2)
apm.addTransactionFilter(filter3)
apm.addSpanFilter(filter1)
apm.addSpanFilter(filter2)
apm.addSpanFilter(filter3)
apm.addMetadataFilter(filter1)
apm.addMetadataFilter(filter2)
apm.addMetadataFilter(filter3)

apm.flush()
apm.flush(() => {})

apm.destroy()

apm.logger.trace('')
apm.logger.debug('')
apm.logger.info('')
apm.logger.warn('')
apm.logger.error('')
apm.logger.fatal('')

{
const trans = agent.startTransaction()
const trans = apm.startTransaction()
if (trans) {
trans.traceparent.split('-')

Expand Down Expand Up @@ -185,7 +185,7 @@ agent.logger.fatal('')
}

{
const trans = agent.startTransaction()
const trans = apm.startTransaction()
if (trans) {
const span = trans.startSpan()
if (span) {
Expand Down

0 comments on commit e1a9a79

Please sign in to comment.