Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Ingestión con Vector

View as MarkdownEdit this pageReport an issueSet up docs MCP

Vector es una canalización de datos de observabilidad de alto rendimiento y agnóstica respecto del proveedor. Se usa habitualmente para recopilar, transformar y enrutar logs y métricas desde una amplia variedad de fuentes, y es especialmente popular para la ingestión de logs por su flexibilidad y bajo consumo de recursos.

Al usar Vector con ClickStack, los usuarios son responsables de definir sus propios esquemas. Estos esquemas pueden seguir las convenciones de OpenTelemetry, pero también pueden ser completamente personalizados y representar estructuras de eventos definidas por el usuario. En la práctica, la ingestión con Vector se usa con mayor frecuencia para logs, cuando los usuarios quieren un control total sobre el análisis y el enriquecimiento antes de que los datos se escriban en ClickHouse.

Esta guía se centra en incorporar datos a ClickStack usando Vector, tanto para ClickStack Open Source como para Managed ClickStack. Para simplificar, no cubre en profundidad las fuentes de Vector ni la configuración de la pipeline. En su lugar, se centra en configurar el sink que escribe datos en ClickHouse y en garantizar que el esquema resultante sea compatible con ClickStack.

El único requisito estricto de ClickStack, tanto en la implementación open source como en la administrada, es que los datos incluyan una columna de marca temporal (o un campo de tiempo equivalente), que puede declararse al configurar la fuente de datos en la UI de ClickStack.

Envío de datos con Vector


La siguiente guía asume que ya ha creado un servicio de Managed ClickStack y ha anotado las credenciales del servicio. Si no lo ha hecho, siga la guía de Getting Started para Managed ClickStack hasta que se le indique configurar Vector.

Crear una base de datos y una tabla

Vector requiere que la tabla y el esquema estén definidos antes de la ingestión de datos.

Primero, cree una base de datos. Puede hacerlo desde la consola de ClickHouse Cloud.

En el ejemplo siguiente, usamos logs:

CREATE DATABASE IF NOT EXISTS logs

Cree una tabla para sus datos. Debe coincidir con el esquema de salida de estos. El ejemplo siguiente parte de una estructura clásica de Nginx. Ajústela según sus datos, siguiendo las buenas prácticas de esquema. Le recomendamos encarecidamente que se familiarice con el concepto de claves primarias y que seleccione su clave primaria según las directrices descritas aquí.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Añade el sink de ClickHouse a la configuración de Vector

Modifica la configuración de Vector para incluir el sink de ClickHouse y actualiza el campo inputs para que reciba eventos de tus canalizaciones existentes.

Esta configuración asume que tu pipeline previo de Vector ya ha preparado los datos para ajustarse al schema objetivo de ClickHouse, es decir, que los campos ya se han parseado, tienen los nombres correctos y los tipos adecuados para la inserción. Consulta el ejemplo de Nginx a continuación para ver una ilustración completa de cómo parsear y normalizar líneas de log sin procesar en un schema adecuado para ClickStack.

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

Por defecto, recomendamos usar el formato json_each_row, que codifica cada evento como un único objeto JSON por fila. Este es el formato predeterminado y recomendado para ClickStack al ingestar datos JSON, y debe preferirse a formatos alternativos, como los objetos JSON codificados como cadenas.

El sink de ClickHouse también admite codificación Arrow stream (actualmente en beta). Esto puede ofrecer un mayor rendimiento, pero conlleva restricciones importantes: la base de datos y la tabla deben ser estáticas, ya que el esquema se obtiene una sola vez al iniciar, y no se admite el enrutamiento dinámico. Por este motivo, la codificación Arrow es más adecuada para canalizaciones de ingestión fijas y bien definidas.

Recomendamos revisar las opciones de configuración disponibles del sink en la documentación de Vector:

Crear un origen de datos

Crea un origen de datos para logs. Si no existe ningún origen de datos, se te pedirá que crees uno al iniciar sesión por primera vez. De lo contrario, ve a configuración del equipo y añade un nuevo origen de datos.

Crear origen de datos - vector

La configuración anterior asume un esquema de estilo Nginx con una columna time_local usada como timestamp. Siempre que sea posible, esta debería ser la columna de timestamp declarada en la clave primaria. Esta columna es obligatoria.

También recomendamos actualizar Default SELECT para definir explícitamente qué columnas se devuelven en la vista de logs. Si hay campos adicionales disponibles, como el nombre del servicio, el nivel de log o una columna body, también se pueden configurar. La columna de visualización del timestamp también se puede sobrescribir si es distinta de la columna usada en la clave primaria de la tabla y configurada anteriormente.

En el ejemplo anterior, no existe una columna Body en los datos. En su lugar, se define mediante una expresión SQL que reconstruye una línea de log de Nginx a partir de los campos disponibles.

Para ver otras opciones posibles, consulta la referencia de configuración.

Explora los datos

Ve a la vista de logs para explorar los datos y empezar a usar ClickStack.

Logs de Nginx en ClickStack

Conjunto de datos de ejemplo con Vector

Para ver un ejemplo más completo, a continuación usamos un archivo de logs de Nginx.

La siguiente guía asume que ya ha creado un servicio de Managed ClickStack y ha guardado las credenciales del servicio. Si aún no lo ha hecho, siga la guía de Getting Started para Managed ClickStack hasta que se le indique configurar Vector.

Instalación de Vector

Antes de continuar, asegúrese de que Vector esté instalado en el sistema donde planea ejecutar su pipeline de ingestión. Siga la guía oficial de instalación de Vector para instalar un binario precompilado o un paquete adecuado para su entorno:

Una vez instalado, verifique que el binario vector esté disponible en su PATH antes de continuar con los pasos de configuración que se indican a continuación.

Puede instalarlo en la misma instancia que su OTel collector de ClickStack.

Siga las prácticas recomendadas de arquitectura y seguridad al poner Vector en producción.

Descargar los datos de ejemplo

Si desea experimentar con un conjunto de datos de muestra, descargue el siguiente ejemplo de Nginx.

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

Crear una base de datos y una tabla

Vector requiere que se definan una tabla y un esquema antes de la ingestión de datos.

Primero, cree una base de datos. Esto puede hacerse desde la consola de ClickHouse Cloud.

Cree una base de datos logs:

CREATE DATABASE IF NOT EXISTS logs

Cree una tabla para sus datos.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Copiar la configuración de Vector

Copia la configuración de Vector y crea un archivo nginx.yaml, donde debes establecer CLICKHOUSE_ENDPOINT y CLICKHOUSE_PASSWORD.

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

Iniciar Vector

Inicie Vector con el siguiente comando y cree primero el directorio de datos para registrar los offsets de archivo.

mkdir ./.vector-data
vector --config nginx.yaml

Crear un origen de datos

Crea un origen de datos de logs. Si no existe ningún origen de datos, se te pedirá que crees uno al iniciar sesión por primera vez. De lo contrario, ve a configuración del equipo y añade un nuevo origen de datos.

Crear origen de datos - vector

La configuración asume el esquema de Nginx, con una columna time_local utilizada como timestamp. Esta es la columna de timestamp declarada en la clave primaria. Esta columna es obligatoria.

También hemos especificado como selección predeterminada time_local, remote_addr, status, request, lo que define qué columnas se devuelven en la vista de logs.

En el ejemplo anterior, no existe una columna Body en los datos. En su lugar, se define como la expresión SQL:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

Esto reconstruye la línea de registro a partir de los campos estructurados.

Para ver otras opciones posibles, consulta la referencia de configuración.

Explora los datos

Ve a la vista de búsqueda de 20 de octubre de 2025 para explorar los datos y empezar a usar ClickStack.

Interfaz de HyperDX
Navigation