Skip to content

Conversation

@JStickler
Copy link
Contributor

@JStickler JStickler commented Dec 2, 2025

What this PR does / why we need it:

  • Adds a new topic, Troubleshooting Ingest
  • Adds a new topic, Monitoring and alerting ingest
  • Adds recommended production limits to the Configuration Best Practices topic.

Special notes for your reviewer:

AI authored using VSCode + VSCode + Claude Sonnet 4 and Cursor + Claude Sonnet 4.5. Two different drafts were generated, then merged and standardized.

Prompts:

  • Acting as an experienced technical writer with knowledge of Loki, write a troubleshooting guide for ingesting logs into Loki. Using error messages in the code base and defaults listed in the configuration documentation, document Loki’s error messages, the causes, and what users should do when encountering errors ingesting logs and writing logs to storage.
  • Revise and replace Promtail configuration with Alloy configuration.
  • Using the following structure: Error message, Cause, Default configuration, Resolution, Properties, fill in any missing details in troubleshooting-ingest.md.
  • Add context to the section "Monitoring and alerting". What is the file name where users should include this code example?

This topic is for OSS Loki, but I'd love to reuse it for Cloud Logs. I could use some help flagging which errors would require contacting Grafana Support. And also if any of the errors are "self-healing" in Cloud due to autoscaling, etc.

Checklist

  • Reviewed the CONTRIBUTING.md guide (required)
  • Documentation added
  • Tests updated
  • Title matches the required conventional commits format, see here
    • Note that Promtail is considered to be feature complete, and future development for logs collection will be in Grafana Alloy. As such, feat PRs are unlikely to be accepted unless a case can be made for the feature actually being a bug fix to existing behavior.
  • Changes that require user attention or interaction to upgrade are documented in docs/sources/setup/upgrade/_index.md
  • If the change is deprecating or removing a configuration option, update the deprecated-config.yaml and deleted-config.yaml files respectively in the tools/deprecated-config-checker directory. Example PR

@JStickler JStickler requested a review from a team as a code owner December 2, 2025 22:16
@JStickler JStickler added the type/docs Issues related to technical documentation; the Docs Squad uses this label across many repositories label Dec 2, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Dec 2, 2025

💻 Deploy preview available (docs: Add ingestion troubleshooting topic):

@JStickler JStickler force-pushed the 2025.12.02_troubleshooting-ingest branch 2 times, most recently from 24930d6 to 8a30170 Compare December 2, 2025 22:41
@JStickler JStickler force-pushed the 2025.12.02_troubleshooting-ingest branch from 8a30170 to 2c51e88 Compare December 2, 2025 22:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/XXL type/docs Issues related to technical documentation; the Docs Squad uses this label across many repositories

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant