Tracing

The Trace class allows you to:

• control the categories of messages you log to the console
• disable multiple messages logging at once
• handle errors

Using Trace ​

The following 3 steps outline the basic usage of the Trace class.

The first two step should be executed earlier in your applicaton, usually in the app.ts file.

1. Specify atleast one category to trace:

   ts

   Trace.setCategories("category"))
   // or
   Trace.setCategories(Trace.categories.concat("category1","category2"));
   //or
   Trace.addCategories("categ1, categ2")

If you don't set any category or the category you pass to Trace.write() is not one of the registered, Trace.write's message won't be logged.

2. Enable tracing

   ts

   Trace.enable()

3. Instead of using console.log(), use Trace.write() to log your messages. Pass the message content, a category name, and optionally, a message type as arguments to Trace.write(). Make sure that the category you provide is one of the categories you have previously set using Trace.setCategories().

   ts

   Trace.write('some message', 'category')

Creating custom Trace writer ​

For an example, see app/trace/trace-writer.ts in the editor below.

Registering custom trace writer ​

To utilize a custom TraceWriter instance, you need to register it with the Trace module by using the addWriter() method. This ensures that your custom writer is recognized and incorporated into the Trace functionality.

Trace.clearWriters()
Trace.addWriter(new TimestampConsoleWriter())

Error handling ​

The Trace module allows to create a custom error handler, register(in the app.ts) it with setErrorHandler, and pass the errors to it with error.

const errorHandler: TraceErrorHandler = {
  handlerError(err) {
    // Option 1 (development) - throw the error
    throw err

    // Option 2 (development) - logging the error via write method provided from trace module
    Trace.write(err, 'unhandled-error', type.error)

    // (production) - custom functionality for error handling
    reportToAnalytics(err)
  },
}

// Register errorHandler
Trace.setErrorHandler(errorHandler)

Trace API ​

addCategories and setCategories ​

Trace.addCategories(categories: string)

Adds categories to existing categories the module will trace. categories is a comma-separated list of categories.

addWriter ​

Trace.addWriter(writer: TraceWriter)

Adds a TraceWriter instance to the trace module.

clearWriters ​

Trace.clearWriters()

Clears all the writers from the trace module. Call this methods before adding a custom trace writer to avoid pre-registered writers from interfering with it.

disable ​

If you've placed several console.logs in your code for debugging, you might want to comment them out before you send the app to production. That may mean tediously having to locate each console.log. By calling once Trace.disable(), you disable all the Trace.write()calls in your code.

Trace.disable()

Disables the tracing.

enable ​

Trace.enable()

Enables the tracing.

error ​

Trace.error(error: string | Error)

Passes an error to the registered TraceErrorHandler.

getErrorHandler ​

Trace.getErrorHandler()

Gets the registered TraceErrorHandler.

setErrorHandler ​

Trace.setErrorHandler(handler: TraceErrorHandler)

Registers an error handler.

isCategorySet ​

Trace.isCategorySet(category: string)

Check if a category is already set in trace module.

isEnabled() ​

Trace.isEnabled()

Returns a boolean for whether tracing is enabled or not.

notifyEvent ​

Trace.notifyEvent(object: Object, name: string, data?: any)

Notifies all the attached listeners for an event that has occurred in the sender object.

removeWriter ​

Trace.removeWriter(writer: TraceWriter)

Removes a TraceWriter instance from the trace module.

write ​

Trace.write(message: any, category: string, type?: number)

Writes a message using the available writers.

API References ​