Package org.microproxy.starlark

Class ScriptTrace

java.lang.Object
org.microproxy.starlark.ScriptTrace
All Implemented Interfaces:
org.microproxy.thirdparty.starlark.eval.StarlarkValue
public final class ScriptTrace extends Object implements org.microproxy.thirdparty.starlark.eval.StarlarkValue
The trace module: the distributed trace of the exchange a hook runs for (see microproxy-otel), whose span a script can add attributes and events to: trace.set_attribute("tenant", "acme"), trace.add_event("rule.matched", {"rule": "r1"}). ctx.trace_id and ctx.span_id read its ids. The calls add to the exchange's span (the tunnel's or flow's, in the TCP, UDP and QUIC hooks), not to the span of the hook call itself (ScriptSpans): what a script notes describes the exchange, and stays on its span however many hooks see it. In a hook without an exchange (upstream, a QUIC framer), or without a tracer, or when the exchange is not sampled, the calls do nothing. Values are strings, booleans, ints, floats, or lists of those; others are recorded as their str().

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addEvent(String name, org.microproxy.thirdparty.starlark.eval.Dict<?,?> attributes, org.microproxy.thirdparty.starlark.eval.StarlarkThread thread)
    trace.add_event(name, attributes={}): adds an event, now, to the exchange's span.
    boolean
    isRecording(org.microproxy.thirdparty.starlark.eval.StarlarkThread thread)
    trace.is_recording(): whether the exchange's span is recorded (sampled), so a script can skip computing attributes nobody will see.
    void
    setAttribute(String key, Object value, org.microproxy.thirdparty.starlark.eval.StarlarkThread thread)
    trace.set_attribute(key, value): sets an attribute of the exchange's span.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.microproxy.thirdparty.starlark.eval.StarlarkValue

    checkHashable, debugPrint, getStarlarkType, isAcyclic, isImmutable, repr, str, truth

  • Method Details

    • setAttribute

      public void setAttribute(String key, Object value, org.microproxy.thirdparty.starlark.eval.StarlarkThread thread) throws org.microproxy.thirdparty.starlark.eval.EvalException
      trace.set_attribute(key, value): sets an attribute of the exchange's span.
      Parameters:
      key - the attribute's name
      value - its value
      thread - the calling thread
      Throws:
      org.microproxy.thirdparty.starlark.eval.EvalException - if the key is empty

    • addEvent

      public void addEvent(String name, org.microproxy.thirdparty.starlark.eval.Dict<?,?> attributes, org.microproxy.thirdparty.starlark.eval.StarlarkThread thread) throws org.microproxy.thirdparty.starlark.eval.EvalException
      trace.add_event(name, attributes={}): adds an event, now, to the exchange's span.
      Parameters:
      name - the event's name
      attributes - the event's attributes
      thread - the calling thread
      Throws:
      org.microproxy.thirdparty.starlark.eval.EvalException - if an attribute's name is not a string

    • isRecording

      public boolean isRecording(org.microproxy.thirdparty.starlark.eval.StarlarkThread thread)
      trace.is_recording(): whether the exchange's span is recorded (sampled), so a script can skip computing attributes nobody will see.
      Parameters:
      thread - the calling thread
      Returns:
      whether the span is recorded