Docs feedback: /docs/sources/send-data/promtail/stages/pack.md

[Feuermurmel]

I think the following sentence is incorrect:

The pack stage is a transform stage which lets you embed extracted values and labels into the log line by packing the log line and labels inside a JSON object.

In my tests, I was unable to insert a label into the packed JSON object, while inserting a value from the extraction map works.

I'm using the following pipeline, which inserts the entry foo_extraction_map = hello-1 into the extraction map and the entry foo_labels = hello-2 into the labels:

clients:
- url: http://localhost

scrape_configs:
- job_name: test
  pipeline_stages:
    - template:
        source: extraction_map_entry
        template: hello-1
    - static_labels:
        labels_entry: hello-2
    - pack:
        labels: [extraction_map_entry, labels_entry]

The produced log line (when running with --dry-run) looks like this:

2024-06-05T17:04:24.885895196+0200  {labels_entry="hello-2"}    {"extraction_map_entry":"hello-1","_entry":"hello"}

This means that pack was able to "see" extraction_map_entry from the extraction map, but not labels_entry from the labels.

[derek-cadzow]

@Feuermurmel is this a doc or a code bug? And which document did you see this sentence in? (URL?)

[Feuermurmel]

is this a doc or a code bug?

I don't know. I did not find enough guidance in the Promtail docs to figure out what the general concepts are, e.g. behind the separation of the extraction map and labels, which stages and other parts of the configuration (e.g. relabeling) affect which, etc. I think the docs are unclear or ambiguous in many places when it comes to data transformation in Promtail.

I think what would help would be:

• An overview document explaining the important concepts of Promtail and how they interact.
• A glossary, maybe part of the overview document.
• Someone going through the complete Promtail documentation making sure that the same terms are always used to refer to the same things and that the same things are always referred to using the same terms.

And which document did you see this sentence in? (URL?)

It's this page: https://grafana.com/docs/loki/latest/send-data/promtail/stages/pack/

I got here by clicking on "Contribute to docs" on the bottom of the page. This automatically placed the file name in the title. I hoped that would be enough context.