elastic / elastic/integrations

[Nginx]: Add configuration examples for Nginx logs compatible with the integration in the documentation

Open Beginner friendly
#20,859 0 comments 0 reactions 0 assignees View on GitHub
needs:triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.