mirror of
https://git.haproxy.org/git/haproxy.git/
synced 2026-05-04 12:41:00 +02:00
8d8d7e4602
Added the full documentation set for the OpenTelemetry filter. The main README served as the user-facing guide covering build instructions, core OpenTelemetry concepts, the complete filter configuration reference, usage examples with worked scenarios, CLI commands, and known limitations. Supplementary documents provided a detailed configuration guide with worked examples (README-configuration), an internal C structure reference for developers (README-conf), a function reference organized by source file (README-func), an architecture and implementation review (README-implementation), and miscellaneous notes (README-misc).
102 lines
4.5 KiB
Plaintext
102 lines
4.5 KiB
Plaintext
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.
|