README-misc

OpenTelemetry filter -- miscellaneous notes
==============================================================================

1  Parsing sample expressions in HAProxy
------------------------------------------------------------------------------

HAProxy provides two entry points for turning a configuration string into an
evaluable sample expression.


1.1  sample_parse_expr()
..............................................................................

Parses a bare sample-fetch name with an optional converter chain.  The input is
the raw expression without any surrounding syntax.

  Declared in:  include/haproxy/sample.h
  Defined in:   src/sample.c

  struct sample_expr *sample_parse_expr(char **str, int *idx, const char *file, int line, char **err_msg, struct arg_list *al, char **endptr);

The function reads from str[*idx] and advances *idx past the consumed tokens.

Configuration example (otel-scope instrument keyword):

  instrument my_counter "name" desc req.hdr(host),lower ...

Here "req.hdr(host),lower" is a single configuration token that
sample_parse_expr() receives directly.  It recognises the fetch "req.hdr(host)"
and the converter "lower" separated by a comma.


1.2  parse_logformat_string()
..............................................................................

Parses a log-format string that may contain literal text mixed with sample
expressions wrapped in %[...] delimiters.

  Declared in:  include/haproxy/log.h
  Defined in:   src/log.c

  int parse_logformat_string(const char *fmt, struct proxy *curproxy, struct lf_expr *lf_expr, int options, int cap, char **err);

Configuration example (HAProxy log-format directive):

  log-format "host=%[req.hdr(host),lower] status=%[status]"

The %[...] wrapper tells parse_logformat_string() where each embedded sample
expression begins and ends.  The text outside the brackets ("host=", " status=")
is emitted as-is.


1.3  Which one to use
..............................................................................

Use sample_parse_expr() when the configuration token is a single, standalone
sample expression (no surrounding text).  This is the case for the otel filter
keywords such as "attribute", "event", "baggage", "status", "value", and
similar, whenever the value does not start with "%[".

Use parse_logformat_string() when the value is a free-form string that may mix
literal text with zero or more embedded expressions.  The otel filter takes
this path for a value that starts with "%[", so the choice is made per value
rather than per keyword.


2  Signal keywords
------------------------------------------------------------------------------

The OTel filter configuration uses one keyword per signal to create or update
signal-specific objects.  The keyword names follow the OpenTelemetry
specification's own terminology rather than using informal synonyms.

  Signal      Keyword        Creates / updates
  --------    -----------    ------------------------------------------
  Tracing     span           A trace span.
  Metrics     instrument     A metric instrument (counter, gauge, ...).
  Logging     log-record     A log record.

The tracing keyword follows the same logic.  A "trace" is the complete
end-to-end path of a request through a distributed system, composed of one or
more "spans".  Each span represents a single unit of work within that trace.
The configuration operates at the span level: it creates individual spans, sets
their parent-child relationships, and attaches attributes and events.  Using
"trace" as the keyword would be imprecise because one does not configure a trace
directly; one configures the spans that collectively form a trace.

The metrics keyword is analogous.  In the OpenTelemetry data model the
terminology is layered: a "metric" is the aggregated output that the SDK
produces after processing recorded measurements, while an "instrument" is the
concrete object through which those measurements are recorded -- a counter,
histogram, gauge, or up-down counter.  The configuration operates at the
instrument level: it creates an instrument of a specific type and records values
through it.  Using "metric" as the keyword would be imprecise because one does
not configure a metric directly; one configures an instrument that yields
metrics.

The logging keyword follows the same pattern.  A "log" is the broad signal
category, while a "log record" is a single discrete entry within that signal.
The configuration operates at the log-record level: it creates individual log
records with a severity, a body, and optional attributes and span context.
Using "log" as the keyword would be imprecise because one does not configure a
log stream directly; one configures the individual log records that comprise it.