Help needed with the tracing API.

[smyrgeorge]

Hello,

I would like to hear you opinions about the tracing API.

The current API looks like:

private val trace: Tracer = Tracer.of(this::class)
// We need to manually register an appender.
// The [SimpleConsoleTracingAppender] will print the traces in the console
// (is just an example, should not be used as a real example).
RootLogger.Tracing.register(SimpleConsoleTracingAppender())

// Create the span and then start it.
val span: TracingEvent.Span = trace.span("test").start()
span.event(name = "test-event")
// Close the span manually.
span.end()

Or you can also do:

// Create the parent span.
// NOTICE: we do not start it, since it's already started.
val parent: TracingEvent.Span = trace.span(id = "PARENT_SPAN_ID", traceId = "TRACE_ID", name = "parent")
// Starts immediately the span.
trace.span("test", parent) {
    // Set span attributes.
    it.attributes["key"] = "value"
    // Send events that are related to the current span.
    it.event(name = "event-1", level = Level.DEBUG)
    it.debug(name = "event-1") // Same as event(name = "event-1", level = Level.DEBUG)
    // Include attributes in the event.
    it.event(name = "event-2", attributes = mapOf("key" to "value"))
    it.event(name = "event-2") { attrs: MutableMap<String, Any?> ->
        attrs["key"] = "value"
    }
    // Automatically closes at the end of te scope.
}

Also, I'm planning to start implementing the Metrics API, so I would like to hear your opinion.

What else should I provide?
Any ideas?

[scribe]

Hello,
I've been trying out log4k and there is a lot I love!

In your second example do I need to close parent myself?

[smyrgeorge]

The parent process is responsible to close the parent span.

The example shows how to create the parent span. This is necessary for example in cases that the parent "lives" outside of your application, thus you need to instantiate it and keep it as a reference, so you can pass it to the logging function or to new spans that you will create.

[smyrgeorge]

Maybe I could rename (or create an alias) this function, so that will be mor self explanatory.

// something like:
trace.parent(..)

And then this kind of span will not expose the start/end method.

What do you think?

[smyrgeorge]

I just released version 0.18.0

Here is the updated example:

// Starts immediately the span.
trace.span("test") {
    // it is [TracingEvent.Span.Local]
    // Set span attributes.
    it.attributes["key"] = "value"
    // Send events that are related to the current span.
    it.event(name = "event-1", level = Level.DEBUG)
    it.debug(name = "event-1") // Same as event(name = "event-1", level = Level.DEBUG)
    // Include attributes in the event.
    it.event(name = "event-2", attributes = mapOf("key" to "value"))
    it.event(name = "event-2") { attrs: MutableMap<String, Any?> ->
        attrs["key"] = "value"
    }
    // Automatically closes at the end of te scope.
}

Additionally, you can instantiate a span that represents the parent span.
This is useful in cases that the parent span is created outside our application (e.g. received from an HTTP call).

// Create the parent span.
// NOTICE: we do not start it, since it's already started.
val parent: TracingEvent.Span.Remote = trace.span(id = "ID_EXAMPLE", traceId = "TRACE_ID_EXAMPLE")
trace.span("test", parent) {
    // Your logic here
}

Introduced two variations of the Span class:

• Span.Local: Represents a span created locally within our application, exposing all methods such as start, end,
  event, debug, info, and more.
• Span.Remote: Represents a span created outside our application and propagated to us (e.g., from an HTTP call). It
  does not expose any methods and serves only as a reference to the parent remote span.

I hope now should be more clear.

PS: if in your code you have specified the types (of the span) explicitly, you will have a breaking change.
You can write it like this and you should be fine:

val parent = trace.span(id = "ID_EXAMPLE", traceId = "TRACE_ID_EXAMPLE")