elastic / elastic/integrations
[Nginx]: Add configuration examples for Nginx logs compatible with the integration in the documentation
- Dominant language
- Handlebars
- Stars
- 333
- Forks
- 647
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 209
Description
### Integration Name
Nginx [packages/nginx]
### Dataset Name
nginx.access (and nginx.error)
### Integration Version
3.2.2
### Agent Version
9.4.4
### OS Version and Architecture
RHEL 9 x86_64
### User Goal
We are using the Nginx integration with Elastic Agent to collect and parse access and error logs. However, the current documentation lacks clear, practical examples of Nginx `log_format` configurations that are fully compatible with the integration's default parsing pipeline.
We would like to see official configuration examples added to the documentation or integration overview page that show:
- The recommended Nginx `log_format` directive to use with the integration.
- Examples for both access logs and error logs.
*Example of a custom log format that users might try:*
```
log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_time $upstream_response_time';
```
Adding these examples would significantly improve the user experience and reduce prep time.
### Existing Features
The current documentation describes how to enable the integration and configure basic paths for log files, but it does not provide concrete `log_format` examples. Users are left to guess which fields are expected by the integration's ingest pipeline. It would be useful to have in hand a direct example.
### What did you see?
Currently, when users configure a custom `log_format` in Nginx that deviates from the default combined format, the integration may fail to parse logs correctly, resulting in:
- Missing or incorrectly mapped fields in Elasticsearch.
- Users having to reverse-engineer the integration's pipeline to understand the expected format.
### Anything else?
It would be very helpful if the documentation included:
1. The **default log format** that the integration expects (if any).
2. A **recommended `log_format`** that works out of the box with the integration with all features.
3. Examples of **common customizations** (e.g., adding response time, upstream status, etc.) and how to adjust the integration's processor configuration to handle them.
Contributor guide
Research direction
Start in the Nginx integration at packages/nginx and review its existing documentation, default parsing pipeline, and processor configuration. Add practical access and error log_format examples, including the expected default format and supported customization guidance. Done means users can configure Nginx logs without reverse-engineering the ingest pipeline.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nginx
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100