# Controlador de registro Fluentd


El controlador de registro `fluentd` envía los registros de los contenedores al recolector de [Fluentd](https://www.fluentd.org) en forma de datos de registro estructurados. A continuación, los usuarios pueden emplear cualquiera de los [diversos complementos (plugins) de salida de Fluentd](https://www.fluentd.org/plugins) para escribir estos registros en diferentes destinos.

Además del propio mensaje de registro, el controlador de registro `fluentd` envía los siguientes metadatos en el mensaje de registro estructurado:

| Campo            | Descripción                                                                                                                                                                                   |
| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `container_id`   | El ID completo del contenedor de 64 caracteres.                                                                                                                                               |
| `container_name` | El nombre del contenedor en el momento en que se inició. Si utilizas `docker rename` para renombrar un contenedor, el nuevo nombre no se refleja en las entradas del diario.                |
| `source`         | `stdout` o `stderr`                                                                                                                                                                           |
| `log`            | El registro del contenedor                                                                                                                                                                    |

## Uso

Se admiten algunas opciones especificando `--log-opt` tantas veces como sea necesario:

- `fluentd-address`: especifica una dirección de socket para conectarse al demonio de Fluentd, por ejemplo `fluentdhost:24224` o `unix:///ruta/al/fluentd.sock`.
- `tag`: especifica una etiqueta para los mensajes de Fluentd. Admite algunas marcas de plantilla de Go, por ejemplo `{{.ID}}`, `{{.FullID}}` o `{{.Name}}` `docker.{{.ID}}`.

Para usar el controlador `fluentd` como el controlador de registro predeterminado, establece las claves `log-driver` y `log-opt` con los valores adecuados en el archivo `daemon.json`. Para obtener más información sobre cómo configurar Docker mediante `daemon.json`, consulta [daemon.json](/reference/cli/dockerd/#daemon-configuration-file).



> [!NOTE]
>
> Si usas Docker Desktop, edita la configuración del demonio a través del
> panel de Docker Desktop. Abre **Settings** y selecciona **Docker Engine**.
> Para más detalles, consulta
> [Configuración de Docker Engine](/desktop/settings-and-maintenance/settings/#docker-engine).


El siguiente ejemplo establece el controlador de registro en `fluentd` y configura la opción `fluentd-address`.

```json
{
  "log-driver": "fluentd",
  "log-opts": {
    "fluentd-address": "fluentdhost:24224"
  }
}
```

Reinicia Docker para que los cambios surtan efecto.

> [!NOTE]
>
> Las opciones de configuración de `log-opts` en el archivo de configuración `daemon.json` deben proporcionarse como cadenas. Los valores booleanos y numéricos (como el valor para `fluentd-async` o `fluentd-max-retries`) deben, por lo tanto, estar entre comillas (`"`).

Para establecer el controlador de registro para un contenedor específico, pasa la opción `--log-driver` a `docker run`:

```console
$ docker run --log-driver=fluentd ...
```

Antes de utilizar este controlador de registro, inicia un demonio de Fluentd. El controlador de registro se conecta a este demonio a través de `localhost:24224` de forma predeterminada. Utiliza la opción `fluentd-address` para conectarte a una dirección diferente.

```console
$ docker run --log-driver=fluentd --log-opt fluentd-address=fluentdhost:24224
```

Si el contenedor no puede conectarse al demonio de Fluentd, el contenedor se detiene inmediatamente a menos que se utilice la opción `fluentd-async`.

## Opciones

Los usuarios pueden utilizar la opción `--log-opt NOMBRE=VALOR` para especificar opciones adicionales del controlador de registro de Fluentd.

### fluentd-address

Por defecto, el controlador de registro se conecta a `localhost:24224`. Proporciona la opción `fluentd-address` para conectarte a una dirección diferente. Se admiten sockets `tcp` (predeterminado) y `unix`.

```console
$ docker run --log-driver=fluentd --log-opt fluentd-address=fluentdhost:24224
$ docker run --log-driver=fluentd --log-opt fluentd-address=tcp://fluentdhost:24224
$ docker run --log-driver=fluentd --log-opt fluentd-address=unix:///ruta/al/fluentd.sock
```

Dos de las opciones anteriores especifican la misma dirección, ya que `tcp` es la predeterminada.

### tag

Por defecto, Docker utiliza los primeros 12 caracteres del ID del contenedor para etiquetar los mensajes de registro. Consulta la [documentación de la opción de etiqueta de registro](/engine/logging/drivers/fluentd/log_tags/) para personalizar el formato de la etiqueta de registro.

### labels, labels-regex, env, y env-regex

Las opciones `labels` y `env` aceptan cada una una lista de claves separadas por comas. Si hay una colisión entre las claves de `label` y `env`, el valor de `env` tiene prioridad. Ambas opciones añaden campos adicionales a los atributos adicionales de un mensaje de registro.

Las opciones `env-regex` y `labels-regex` son similares y compatibles respectivamente con `env` y `labels`. Sus valores son expresiones regulares para hacer coincidir variables de entorno y etiquetas relacionadas con el registro. Se utiliza para opciones avanzadas de [etiquetas de registro](/engine/logging/drivers/fluentd/log_tags/).

### fluentd-async

Docker se conecta a Fluentd en segundo plano. Los mensajes se almacenan en el búfer hasta que se establece la conexión. El valor predeterminado es `false`.

### fluentd-async-reconnect-interval

Cuando `fluentd-async` está habilitado, la opción `fluentd-async-reconnect-interval` define el intervalo, en milisegundos, en el que se restablece la conexión con `fluentd-address`. Esta opción es útil si la dirección se resuelve en una o más direcciones IP, por ejemplo, una dirección de servicio de Consul.

### fluentd-buffer-limit

Establece la cantidad de eventos almacenados en el búfer en memoria. Los registros se almacenarán en memoria hasta este número. Si el búfer está lleno, la llamada para registrar los registros fallará. El valor predeterminado es 1048576.
(https://github.com/fluent/fluent-logger-golang/tree/master#bufferlimit)

### fluentd-retry-wait

Cuánto tiempo esperar entre reintentos. El valor predeterminado es 1 segundo.

### fluentd-max-retries

El número máximo de reintentos. El valor predeterminado es `4294967295` (2\*\*32 - 1).

### fluentd-sub-second-precision

Genera registros de eventos con resolución de nanosegundos. El valor predeterminado es `false`.

### fluentd-write-timeout

Establece el tiempo de espera (timeout) para la llamada de escritura al demonio de `fluentd`. Por defecto, las escrituras no tienen tiempo de espera y se bloquearán indefinidamente.

## Gestión del demonio de Fluentd con Docker

Sobre `Fluentd` en sí, consulta [la página web del proyecto](https://www.fluentd.org) y [sus documentos](https://docs.fluentd.org).

Para usar este controlador de registro, inicia el demonio de `fluentd` en un host. Se recomienda utilizar [la imagen de docker de Fluentd](https://hub.docker.com/r/fluent/fluentd/). Esta imagen es especialmente útil si deseas agregar múltiples registros de contenedores en cada host y, posteriormente, transferir los registros a otro nodo de Fluentd para crear un almacenamiento agregado.

### Probar los registradores del contenedor

1. Escribe un archivo de configuración (`test.conf`) para volcar los registros de entrada:

    ```text
    <source>
      @type forward
    </source>

    <match *>
      @type stdout
    </match>
    ```

2. Inicia el contenedor de Fluentd con este archivo de configuración:

    ```console
    $ docker run -it -p 24224:24224 -v /ruta/a/conf/test.conf:/fluentd/etc/test.conf -e FLUENTD_CONF=test.conf fluent/fluentd:latest
    ```

3. Inicia uno o más contenedores con el controlador de registro `fluentd`:

    ```console
    $ docker run --log-driver=fluentd tu/aplicacion
    ```