artin/sourcegraph
1
0
Fork 0
mirror of https://github.com/sourcegraph/sourcegraph.git synced 2026-02-06 16:51:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/observability: document new OpenTelemetry log format (#34529)

Browse Source
This commit is contained in:
Robert Lin 2022-04-26 14:35:50 -07:00 committed by GitHub
parent 89a37add66
commit aaf2f048ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 37 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
doc/admin/observability/logs.md
View File

@ -1,5 +1,7 @@
# Logs
This document describes the log output from Sourcegraph services and how to configure it.
## Log levels
A Sourcegraph service's log level is configured via the environment variable `SRC_LOG_LEVEL`. The valid values (from most to least verbose) are:
@ -18,5 +20,36 @@ A Sourcegraph service's log output format is configured via the environment vari
* `condensed`: Optimized for human readability.
* `json`: Machine-readable JSON format.
* For certain services and log entries, Sourcegraph exports a [OpenTelemetry-compliant log data model](#opentelemetry).
* `logfmt`: The [logfmt](https://github.com/kr/logfmt) format.
* Note that `logfmt` is no longer supported with [Sourcegraph's new internal logging standards](../../dev/how-to/add_and_use_logging.md) - if you need structured logs, we recommend using `json` instead. If set to `logfmt`, log output from new loggers will be in `condensed` format.
### OpenTelemetry
When [configured to export JSON logs](#log-format), Sourcegraph services that have migrated to the [new internal logging standard](../../dev/how-to/add_and_use_logging.md) that will export a JSON log format compliant with [OpenTelemetry's log data model](https://opentelemetry.io/docs/reference/specification/logs/data-model/):
```json
{
"Timestamp": 1651000257893614000,
"InstrumentationScope": "string",
"SeverityText": "string (DEBUG, INFO, ...)",
"Body": "string",
"Attributes": { "key": "value" },
"Resource": {
"service.name": "string",
"service.version": "string",
"service.instance.id": "string",
},
"TraceId": "string (optional)",
"SpanId": "string (optional)",
}
```
We also include the following non-OpenTelemetry fields:
```json
{
"Caller": "string",
"Function": "string",
}
```

6
doc/dev/how-to/add_and_use_logging.md
View File

@ -1,11 +1,11 @@
# How to add and use logging
> NOTE: Sourcegraph's new logging standards are still a work in progress - please leave a comment in [this discussion](https://github.com/sourcegraph/sourcegraph/discussions/33248) if you have any feedback or ideas!
> NOTE: For how to *use* Sourcegraph's observability and an overview of our observability features, refer to the [observability for site administrators documentation](../../admin/observability/index.md).
The recommended logger at Sourcegraph is `github.com/sourcegraph/sourcegraph/lib/log`, which exports:
1. A standardized, strongly-typed, and structured logging interface, `log.Logger`
1. Production output from this logger (`SRC_LOG_FORMAT=json`) complies with the [OpenTelemetry log data model](https://opentelemetry.io/docs/reference/specification/logs/data-model/)
1. Production output from this logger (`SRC_LOG_FORMAT=json`) complies with the [OpenTelemetry log data model](https://opentelemetry.io/docs/reference/specification/logs/data-model/) (also see: [Logging: OpenTelemetry](../../admin/observability/logs.md#opentelemetry))
2. `log.Logger` has a variety of constructors for spawning new loggers with context, namely `Scoped`, `WithTrace`, and `WithFields`.
2. An initialization function to be called in `func main()`, `log.Init`
1. Log level can be configured with `SRC_LOG_LEVEL`
@ -20,6 +20,8 @@ For testing purposes, we also provide:
1. The standard `logtest.Scoped` will also work after `logtest.Init`
2. Programatically iterable logs are available from the `logtest.Captured` logger instance
> NOTE: Sourcegraph's new logging standards are still a work in progress - please leave a comment in [this discussion](https://github.com/sourcegraph/sourcegraph/discussions/33248) if you have any feedback or ideas!
## Core concepts
1. `lib/log` intentionally does not export directly usable log functions. Users should hold their own references to loggers, so that fields can be attached and log output can be more useful with additional context, and pass `Logger` instances to components as required.