- Recommended Node verison to be v22 or higher
-
tsconfig.json
required compilerOptions
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"moduleResolution": "node16",
}
-
dotenv
npm package installed
You have access to two different decorators/wrappers called @kRun
and @kStep
.
KIMTRACE_ACCESS_KEY_ID = '<Will be provided when you onboard with Kimtrace>'
KIMTRACE_SECRET_ACCESS_KEY = '<Will be provided when you onboard with Kimtrace>'
KIMTRACE_REGION = '<Will be provided when you onboard with Kimtrace - but currently only supports us-east-1>'
KIMTRACE_SQS_URL = '<Will be provided when you onboard with Kimtrace>'
KIMTRACE_CLIENT_ID = '<Will be provided when you onboard with Kimtrace>'
## [OPTIONAL] emergency configuration, "true" will disable Kimtrace, and "false" or null will enable it. Useful when a Kimtrace regression is causing an outage on your service.
#KIMTRACE_DISABLE = true
This decorator is used to initialize Kimtrace, record the initial input and final output of the run, and start the process of recording the subsequent call stacks.
All @kStep
invocations are expected to have been preceeded by a @kRun
invocation.
The decorator variant is@kRun
, and function variant is either @kRunWrapper
or @kRunWrappedCall
.
-
@kRunWrapper
is used when you want to wrap a function and call it later -
@kRunWrappedCall
is used when you want to wrap a function and call it immediately
Here are some additional properties you can configure using @kRun
:
- runId: Sets the run id of the execution, used to identify in the Kimtrace webapp
- runName: Sets the name of the overall run, used to identify in the Kimtrace webapp
- emitOnlyOnFailure: If true, the run will only be emitted if the run fails due to a thrown error. If false or null, the run will be emitted regardless of status.
- tags: An array of property names (string) that will be used to tag the run based on the non-object output from the run's input. If the value is an object, it will be ignored.
Example 1:
if the input is {a: 1, b: 2} and you specify `tags: ["a"]`, it will tag the run with "1"
Example 2:
if the input is {a: {num: 1}, b: 2} and you specify `tags: ["a", "b"]`, it will tag the run with "2"
- redactors: An array of strings that will be used to redact the input and output of the run in the Kimtrace webapp
Example 1: Redacting the input of a nested step based on redactors: ["firstNum"]
:
{
"stepName": "StepWrapper.asyncAdd",
"stepStatus": "success",
"stepInput": "[{\"firstNum\":\"[REDACTED]\",\"secondNum\":88}]",
"stepOutput": "122",
"stepStartTime": "2025-01-03T03:03:10.113Z",
"stepEndTime": "2025-01-03T03:03:10.113Z",
"calledFromId": "4359adfa-fd8a-408f-a376-e6814fee078c",
"id": "75143726-2671-4818-8d82-0b36da012c19"
},
This decorator is used to represent each step in the kRun call stack. If you decorate a class method with this decorator, it record the input and output of that method.
The equivalent of @kStep
is @kStepWrapper
or kStepWrappedCall
.
This only has an additional property of stepName
which has the same functionality as explained previously.
class Main {
public static async run() {
return await FirstNestedClass.runDefault({howManyToAdd: 3});
}
}
class FirstNestedClass {
@kRun({runName: "Set.runName"})
public static async runDefault(params: {howManyToAdd: number}) {
// ... code here
}
}
class Main {
public static async run() {
return wrappedCall = kRunWrapper({runName: "Set.runName"}, FirstNestedClass.runDefault);
return await wrappedCall({howManyToAdd: 3});
}
}
class FirstNestedClass {
public static async runDefault(params: {howManyToAdd: number}) {
// ... code here
}
}
async function run() {
return await kRunWrappedCall(
{runName: "Set.runName"},
runDefault,
{howManyToAdd: 3}
);
}
async function runDefault(params: {howManyToAdd: number}) {
// ... code here
}
class Main {
public static async run() {
return await kRunWrappedCall(
{runName: "Set.runName"},
FirstNestedClass.runDefault,
{howManyToAdd: 3}
);
}
}
class FirstNestedClass {
public static async runDefault(params: {howManyToAdd: number}) {
return DependencyClass.add({firstNum: 1, secondNum: 2});
}
}
class DependencyClass {
@kStep({stepName: "Set.stepName"})
public static add(params: {firstNum: number, secondNum: number}) {
// ... code here
}
}
async function run() {
return await kRunWrappedCall({
runId: "Set.runId",
runName: "Set.runName",
tags: ["howManyToAdd"],
redactors: ["firstNum"],
emitOnlyOnFailure: true
}, runDefault, {
howManyToAdd: 3
});
}
async function runDefault(params: {howManyToAdd: number}) {
// ... code here
}