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.

Use parse_logformat_string() when the value is a free-form string that may mix
literal text with zero or more embedded expressions.


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.