kimtrace

Homepage

https://www.kimtrace.dev/

Dependencies Required

1. Recommended Node verison to be v22 or higher
2. tsconfig.json required compilerOptions

  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "moduleResolution": "node16",
  }

3. dotenv npm package installed

How to Use

You have access to two different decorators/wrappers called @kRun and @kStep.

.env Secrets

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

@kRun

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"
    },

@kStep

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.

Examples

Setting up a @kRun

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
    }
}

Setting up a @kRunWrapper

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
    }
}

Setting up a @kRunWrappedCall

async function run() {
    return await kRunWrappedCall(
        {runName: "Set.runName"}, 
        runDefault, 
        {howManyToAdd: 3}
    );
}

async function runDefault(params:  {howManyToAdd: number}) {
    // ... code here
}

Setting up a @kStep

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
    }
}

Configuring a @kRun

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
}