Implementing subscribers

Implementing Subscribers

The backdrop

Tracer works by collecting traces whenever the trace methods are called on the Tracer autoload. It doesn't do anything with them, however. It simply stores them (it only stores the latest one). To consume traces in a useful way, subscribers are used. Subscribers are objects that receive these traces and can do anything with them. When Tracer collects a new trace, all initialized subscribers are notified via signals.

The why

The default subscriber provided by tracer is made to print out logs to the console. However, traces are useful in other contexts other than logging (e.g error traces). Or maybe you want to implement your own formatting for logs. These are great use cases for implementing a new subscriber.

A new subscriber from scratch

Let's implement a simple subscriber. This is what you need:

extends Node

func init() -> void:
  # add self as a child of `Tracer`
  Tracer.add_child(self)
  # connect the entered_span signal 
  Tracer.entered_span.connect(on_entered_span)

# called whenever a trace is collected
func on_entered_span() -> void:
  # get the trace
  var trace: Tracer.Trace = Tracer.current_span
  # do your thing 🔥

That's it. Any subscriber should do a few things to work:

• have an init function that
  • should add itself as a child of the global autoload
  • should connect to the entered_span method

In the on_entered_span callback you can obtain the current trace and use it. Ideally, in the future this trace will be passed as an argument instead. It's not as of now because of a bug in godot's static typing that sees Trace and Tracer.Trace as different types. Now, you can do anything with the trace. To see the available properties, read on to the Trace Class Reference.

Trace Class Reference

The Trace class is designed to represent trace messages with various attributes such as trace level, message content, module, function name, timestamp, and thread ID. This class is commonly used in debugging and logging scenarios to capture and display trace information.

Properties

• level: Level: The trace level.
• msg: String: The content of the trace message.
• module: String: The module where the trace message originated.
• function_name: String: The name of the function that generated the trace message.
• timestamp: String: The timestamp of when the trace message was created. It is initialized with the current system datetime.
• thread_id: int: The ID of the thread associated with the trace message. It is initialized to the thread id the function that emitted the trace is running in.