> For the complete documentation index, see [llms.txt](https://vostok.gitbook.io/logging/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vostok.gitbook.io/logging/implementations/console-log.md).

# Console log

**Location**: [console](https://vostok.gitbook.io/logging/modules/console.md) module.

```csharp
var consoleLog = new ConsoleLog();
var configuredConsoleLog = new ConsoleLog(new ConsoleLogSettings());
```

### Features

* Customizable [output templates](https://vostok.gitbook.io/logging/concepts/formatting/output-templates.md).
* Customizable per-level message colors.
* `Log` method is nonblocking: log events are placed into an internal queue, grouped into batches and efficiently written to console output stream in the background.

### Configuration

Here's what `ConsoleLogSettings` have to offer:

| Option           | Default value                                                                                                                                                                                                                                     | Description                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OutputTemplate` | `OutputTemplate.Default`                                                                                                                                                                                                                          | [Output template](https://vostok.gitbook.io/logging/concepts/formatting/output-templates.md) to render log events with.                                |
| `FormatProvider` | `null`                                                                                                                                                                                                                                            | An optional format provider used when applying custom [format specifiers](https://vostok.gitbook.io/logging/concepts/formatting/format-specifiers.md). |
| `ColorsEnabled`  | `false`                                                                                                                                                                                                                                           | Enables/disables coloring of log messages.                                                                                                             |
| `ColorMapping`   | <p><code>Debug</code> => <code>Gray</code>, </p><p><code>Info</code> => <code>White</code>, </p><p><code>Warn</code> => <code>Yellow</code>, </p><p><code>Error</code> => <code>Red</code>, </p><p><code>Fatal</code> => <code>DarkRed</code></p> | Provides a mapping from log levels to console colors.                                                                                                  |

All configuration parameters are optional.

### Global configuration

There's also static global configuration that affects all `ConsoleLog` instances in the application. It is accessed as follows:

```csharp
ConsoleLog.UpdateGlobalSettings(new ConsoleLogGlobalSettings());
```

This configuration exposes following parameters worth mentioning:

| Option                | Default value | Description                                                                            |
| --------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `EventsQueueCapacity` | `50000`       | Maximum count of log events in internal queue.                                         |
| `OutputBufferSize`    | `65536`       | Size of the buffer used when writing log messages to console output stream (in bytes). |

Note that changes in these global configuration parameters only take effect if performed before any actual logging.

### Usage tips

* Keep in mind that log messages are rendered in the background. Use `Flush` or `FlushAsync` methods of `ConsoleLog` to ensure that all logged events have been written to console when the application shuts down.

* Internal queue with limited capacity implies that log messages may be lost in the event of overflow (see [guarantees section](https://vostok.gitbook.io/logging/guarantees.md) for more on this topic). Use `EventsLost` property of a single `ConsoleLog` instance or static `TotalEventsLost` property to check if any events have been discarded.

* If any log events are lost due to internal queue overflow, `ConsoleLog` emits a special diagnostic message that looks like this:
  * ```
    [ConsoleLog] Buffer overflow. 100 log events were lost (events queue capacity = 50000).
    ```

### Synchronous version

There are certain scenarios where it's not feasible to use an asynchronous log, such as logging in unit tests or simple console utilities. These use cases are better served by an alternative synchronous implementation that writes to console immediately in `Log` method:

```csharp
var synchronousLog = new SynchronousConsoleLog();
```

It's performance is vastly inferior to that of `ConsoleLog` due to lack of buffering, but it removes the need to flush and works well in test environments where `Console.Out` cannot be safely cached.
