elastic / elastic/apm

Introduce global logging environment variables

Open
#869 1 comment 0 reactions 0 assignees View on GitHub
apm-agents discussion
Dominant language
Gherkin
Stars
427
Forks
125
PR merge metrics
No merged PRs in 30d

Description

In the .NET agent and OpenTelemetry distribution [we are introducing new OTEL variables](https://github.com/elastic/elastic-otel-dotnet/pull/106) to enable global file logging:

### Overview

* `ELASTIC_OTEL_LOG_LEVEL`
* `ELASTIC_OTEL_LOG_DIRECTORY`
* `ELASTIC_OTEL_LOG_TARGETS`

If any of these are provided the agent or distribution will start logging, regardless of how the application is set up to log.

`ELASTIC_OTEL_LOG_DIRECTORY` defaults to:
- `%PROGRAMDATA%\elastic\apm-agent-dotnet` (on Windows)
- `/var/log/elastic/apm-agent-dotnet` (on Linux)
- `~/Library/Application_Support/elastic/apm-agent-dotnet` (on OSX)

We don't differentiate between agent and distro for the application moniker `apm-agent-dotnet`, should we?

`ELASTIC_OTEL_LOG_TARGETS`

Semicolon separated list of options.

- `file`, enable file logging
- `stdout`, enable logging to stdout
- `none` , explicitly disables global logging.

The default is `none` unless the other two variables are set in which case its `file`

`ELASTIC_OTEL_LOG_LEVEL`
The name of the log level.

- trace => `Trace`,
- debug => `Debug`,
- info, information => `Information`,
- warn, warning => `Warning`,
- error => `Error`,
- none => `None`, explicitly disables global logging.

### Benefit

Troubleshooting the agent becomes rather easy for our users. We only have to instruct them to set `ELASTIC_OTEL_LOG_LEVEL=Trace` to get logs.

Comparing that to what we point users to today: https://www.elastic.co/guide/en/apm/agent/dotnet/current/troubleshooting.html#collect-agent-logs where we first need to find out how the users is running the agent and depending on the actual stack have various different ways to turn on logging. This might be very .NET specific though.

### Discussion

We expect our users to set these variables system wide, even if they don't technically have to.

Should we standardize on these variables to enable logging for our new distributions?
Have one common way to start debugging and troubleshooting them?

Cc @elastic/apm-agent-devs

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.