docs(telegraf): add missing serializer documentation #6654
Conversation
|
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive documentation for six previously undocumented Telegraf output data format serializers and fixes a naming inconsistency. The additions complete the serializer documentation coverage by documenting binary protocol serialization, CloudEvents JSON formatting, CSV output, Prometheus text and remote write formats, and Wavefront data format. The PR also renames the MessagePack documentation file to match Telegraf's actual serializer name and adds an alias to preserve backward compatibility.
Key changes:
- Adds documentation for 6 missing serializers with configuration examples and usage details
- Fixes MessagePack documentation filename and adds backward-compatible alias
- Provides consistent structure across all new documentation files
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| binary.md | Documents binary protocol serializer with configurable entries for field/tag serialization |
| cloudevents.md | Documents CloudEvents JSON format serializer supporting v0.3 and v1.0 specifications |
| csv.md | Documents CSV serializer with customizable columns, timestamps, and separators |
| prometheus.md | Documents Prometheus text exposition format serializer with metric type configuration |
| prometheusremotewrite.md | Documents Prometheus protobuf serializer for remote write endpoints |
| wavefront.md | Documents Wavefront data format serializer with sanitization and source override options |
| msgpack.md | Adds identifier, backward-compatible alias, and minor content improvements |
Comments suppressed due to low confidence (2)
content/telegraf/v1/data_formats/output/msgpack.md:17
- The configuration section uses heading level 3 (###) instead of level 2 (##). For consistency with other serializer documentation files (e.g., json.md, graphite.md, influx.md) which use level 2 headings for "Configuration", this should be changed to level 2.
content/telegraf/v1/data_formats/output/msgpack.md:32 - The configuration section uses heading level 3 (###) instead of level 2 (##). For consistency with other serializer documentation files (e.g., json.md, graphite.md, influx.md) which use level 2 headings for "Example output", this should be changed to level 2.
| [[outputs.file]] | ||
| files = ["stdout"] | ||
|
|
||
| ## Enable batch format for correct histogram/summary output. |
There was a problem hiding this comment.
The configuration example shows use_batch_format = true which is an outputs.file plugin option, not a serializer-specific option. This configuration parameter is not documented in the "Configuration options" table below. Either add this option to the table or add a clarifying comment that this is a file output plugin option, not a prometheus serializer option.
| ## Enable batch format for correct histogram/summary output. | |
| ## Enable batch format for correct histogram/summary output. | |
| ## This is an outputs.file plugin option, not a prometheus serializer option. |
| **Resulting Prometheus metrics:** | ||
| ``` | ||
| cpu_usage_idle{host="server01"} 98.5 | ||
| cpu_usage_user{host="server01"} 1.2 | ||
| ``` |
There was a problem hiding this comment.
The example shows Prometheus metrics in text exposition format, but the prometheusremotewrite serializer outputs Prometheus protobuf format for remote write endpoints. The example should clarify that this shows the logical representation of the metrics, not the actual binary protobuf output. Consider adding a note like "Logical representation (actual output is binary protobuf format):" before the example.
There was a problem hiding this comment.
@copilot open a new pull request to apply changes based on this feedback
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Add documentation for missing output data formats (serializers): - binary: Binary protocol serialization with configurable entries - cloudevents: CloudEvents JSON format (v0.3 and v1.0) - csv: Comma-separated values with configurable columns - prometheus: Prometheus text exposition format - prometheusremotewrite: Prometheus protobuf for remote write - wavefront: Wavefront data format Also fixes: - Rename messagepack.md to msgpack.md to match Telegraf source This completes the serializer documentation coverage.
…epresentation (#6661) * Initial plan * docs(telegraf): clarify prometheusremotewrite example shows logical representation Co-authored-by: jstirnaman <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: jstirnaman <[email protected]>
Co-authored-by: Copilot <[email protected]>
jstirnaman
force-pushed
the
template-serializer-docs
branch
from
a532697 to
9f23195
Compare
…n options (#6660) * hotfix(influxdb3): fix duplicate menu entry for Enterprise security page Change menu key from influxdb3_core to influxdb3_enterprise. * chore(influxdb3) Security: style and cleanup: intro, requirements, callouts * fix(influxdb3): restore clean install.md from jdstrand branch Remove duplicate content and fix malformed code blocks introduced during rebase conflict resolution. * docs(telegraf): add design plan for batch format documentation Defines documentation changes to clarify: - Output plugin vs serializer relationship - use_batch_format option location and purpose - Histogram/summary handling with prometheus_client - Choosing the right output approach * docs(telegraf): clarify output plugins, serializers, and batch format - Add "How output plugins use serializers" section explaining the relationship between output plugins and data formats - Add "Choosing an output approach" guidance by destination and metric type - Create prometheus serializer doc with histogram/summary guidance - Add "Use this plugin for..." sections to prometheus_client - Add Data formats subsection to configuration.md - Expand output plugins index with serializer relationship Addresses confusion about use_batch_format being an output plugin option rather than a serializer option, and provides clear guidance on when to use prometheus_client vs the prometheus serializer. --------- Co-authored-by: Jason Stirnaman <[email protected]>
jstirnaman
force-pushed
the
template-serializer-docs
branch
from
9f23195 to
1a14241
Compare
|
@sanderson I updated this PR to explain when to use the |
Add documentation for missing output data formats (serializers):
Also fixes:
This completes the serializer documentation coverage.
Closes #
Describe your proposed changes here.
(if necessary)