Configurar la fuente de datos ClickHouse en Grafana

La forma más sencilla de modificar una configuración es desde la UI de Grafana, en la página de configuración del plugin, pero las fuentes de datos también se pueden aprovisionar con un archivo YAML. Esta página muestra una lista de opciones de configuración disponibles en el plugin de ClickHouse, así como fragmentos de configuración para quienes aprovisionan una fuente de datos con YAML. Para obtener una visión general rápida de todas las opciones, puedes consultar aquí la lista completa de opciones de configuración.

Configuración común

Pantalla de configuración de ejemplo: Ejemplo de configuración YAML para la configuración común:

jsonData:
  host: 127.0.0.1 # (required) server address.
  port: 9000      # (required) server port. For native, defaults to 9440 secure and 9000 insecure. For HTTP, defaults to 8443 secure and 8123 insecure.

  protocol: native # (required) the protocol used for the connection. Can be set to "native" or "http".
  secure: false    # set to true if the connection is secure.

  username: default # the username used for authentication.

  tlsSkipVerify:     <boolean> # skips TLS verification when set to true.
  tlsAuth:           <boolean> # set to true to enable TLS client authentication.
  tlsAuthWithCACert: <boolean> # set to true if CA certificate is provided. Required for verifying self-signed TLS certificates.

secureJsonData:
  password: secureExamplePassword # the password used for authentication.

  tlsCACert:     <string> # TLS CA certificate
  tlsClientCert: <string> # TLS client certificate
  tlsClientKey:  <string> # TLS client key

Ten en cuenta que se añade una propiedad version cuando la configuración se guarda desde la UI. Esto indica la versión del plugin con la que se guardó la configuración.

Protocolo HTTP

Si eliges conectarte mediante el protocolo HTTP, se mostrarán más opciones de configuración.

Ruta HTTP

Si el servidor HTTP está expuesto en una ruta URL diferente, puedes especificarla aquí.

jsonData:
  # excluye la primera barra
  path: additional/path/example

Encabezados HTTP personalizados

Puede añadir encabezados personalizados a las solicitudes enviadas a su servidor. Los encabezados pueden ser de texto sin formato o seguros. Todas las claves de los encabezados se almacenan en texto sin formato, mientras que los valores de los encabezados seguros se guardan en la configuración segura (de forma similar al campo password).

Valores seguros a través de HTTPAunque los valores de los encabezados seguros se almacenan de forma segura en la configuración, el valor seguirá enviándose por HTTP si la conexión segura está deshabilitada.

Ejemplo de YAML para encabezados de texto sin formato/seguros:

jsonData:
  httpHeaders:
  - name: X-Example-Plain-Header
    value: plain text value
    secure: false
  - name: X-Example-Secure-Header
    # "value" se omite
    secure: true
secureJsonData:
  secureHttpHeaders.X-Example-Secure-Header: secure header value

Ajustes adicionales

Estos ajustes adicionales son opcionales. YAML de ejemplo:

jsonData:
  defaultDatabase: default # default database loaded by the query builder. Defaults to "default".
  defaultTable: <string>   # default table loaded by the query builder.

  dialTimeout: 10    # dial timeout when connecting to the server, in seconds. Defaults to "10".
  queryTimeout: 60   # query timeout when running a query, in seconds. Defaults to 60. This requires permissions on the user, if you get a permission error try setting it to "0" to disable it.
  validateSql: false # when set to true, will validate the SQL in the SQL editor.

OpenTelemetry

OpenTelemetry (OTel) está profundamente integrado en el plugin. Los datos de OpenTelemetry se pueden exportar a ClickHouse mediante nuestro plugin exportador. Para un uso óptimo, se recomienda configurar OTel tanto para logs como para trazas. También es necesario configurar estos valores predeterminados para habilitar enlaces de datos, una función que permite flujos de trabajo de observabilidad muy potentes.

Logs

Para agilizar la creación de consultas para logs, puedes configurar una base de datos/tabla predeterminada, así como las columnas para la consulta de logs. Esto precargará el generador de consultas con una consulta de logs lista para ejecutar, lo que acelera la exploración en la página Explore para la observabilidad. Si usas OpenTelemetry, debes activar el interruptor “Usar OTel” y establecer la tabla de logs predeterminada en otel_logs. Esto sustituirá automáticamente las columnas predeterminadas para usar la versión del esquema OTel seleccionada. Aunque OpenTelemetry no es obligatorio para los logs, usar un único conjunto de datos para logs/trazas ayuda a disponer de un flujo de trabajo de observabilidad más fluido con el enlaces de datos. Ejemplo de pantalla de configuración de logs: Ejemplo de YAML de configuración de logs:

jsonData:
  logs:
    defaultDatabase: default # default log database.
    defaultTable: otel_logs  # default log table. If you're using OTel, this should be set to "otel_logs".

    otelEnabled: false  # set to true if OTel is enabled.
    otelVersion: latest # the otel collector schema version to be used. Versions are displayed in the UI, but "latest" will use latest available version in the plugin.

    showLogLinks: true # set to false to hide the "View logs" data links on trace ID fields.

    # Default columns to be selected when opening a new log query. Will be ignored if OTel is enabled.
    timeColumn:       <string> # the primary time column for the log.
    levelColumn:   <string> # the log level/severity of the log. Values typically look like "INFO", "error", or "Debug".
    messageColumn: <string> # the log's message/content.

Desactivación de los enlaces «Ver logs»

La sección Correlación de ID de traza de la configuración de logs contiene el interruptor Mostrar enlaces «Ver logs». Este interruptor controla si el plugin adjunta enlaces «Ver logs» enlaces de datos a los campos de ID de traza de los resultados de las consultas. El interruptor está activado de forma predeterminada. Un enlace «Ver logs» para el mismo tipo de consulta no requiere valores predeterminados de logs configurados; en cambio, un enlace «Ver logs» entre señales desde los resultados de consultas de trazas sí los requiere. Desactive el interruptor o establezca showLogLinks: false en YAML para ocultarlos.

Trazas

Para agilizar la creación de consultas para trazas, puedes establecer una base de datos/tabla predeterminada, así como las columnas de la consulta de trazas. Esto precargará el generador de consultas con una consulta de búsqueda de trazas lista para ejecutar, lo que agiliza la navegación en la página Explore para tareas de observabilidad. Si usas OpenTelemetry, debes activar el interruptor “Usar OTel” y establecer la tabla de trazas predeterminada en otel_traces. Esto sustituirá automáticamente las columnas predeterminadas para usar la versión del esquema de OTel seleccionada. Aunque OpenTelemetry no es obligatorio, esta función funciona mejor cuando se utiliza su esquema para trazas. Pantalla de ejemplo de configuración de trazas: YAML de ejemplo de configuración de trazas:

jsonData:
  traces:
    defaultDatabase: default  # default trace database.
    defaultTable: otel_traces # default trace table. If you're using OTel, this should be set to "otel_traces".

    otelEnabled: false  # set to true if OTel is enabled.
    otelVersion: latest # the otel collector schema version to be used. Versions are displayed in the UI, but "latest" will use latest available version in the plugin.

    showTraceLinks: true # set to false to hide the "View trace" data links on trace ID fields.

    # Default columns to be selected when opening a new trace query. Will be ignored if OTel is enabled.
    traceIdColumn:       <string>    # trace ID column.
    spanIdColumn:        <string>    # span ID column.
    operationNameColumn: <string>    # operation name column.
    parentSpanIdColumn:  <string>    # parent span ID column.
    serviceNameColumn:   <string>    # service name column.
    durationTimeColumn:  <string>    # duration time column.
    durationUnitColumn:  <time unit> # duration time unit. Can be set to "seconds", "milliseconds", "microseconds", or "nanoseconds". For OTel the default is "nanoseconds".
    startTimeColumn:     <string>    # start time column. This is the primary time column for the trace span.
    tagsColumn:          <string>    # tags column. This is expected to be a map type.
    serviceTagsColumn:   <string>    # service tags column. This is expected to be a map type.

Desactivar los enlaces “Ver traza”

La sección Correlación de ID de traza de la configuración de trazas contiene el interruptor Mostrar enlaces “Ver traza”. Este interruptor determina si el plugin adjunta enlaces de datos de “Ver traza” enlace de datos a los campos de ID de traza de los resultados de las consultas. El interruptor está activado de forma predeterminada. Un enlace “Ver traza” para el mismo tipo de consulta no requiere valores predeterminados de traza configurados; uno entre señales desde los resultados de consultas de logs sí los requiere. Desactive el interruptor o establezca showTraceLinks: false en YAML para ocultarlos.

Alias de columnas

Los alias de columnas son una forma práctica de consultar tus datos con distintos nombres y tipos. Mediante alias, puedes tomar un esquema anidado y aplanarlo para seleccionarlo fácilmente en Grafana. El uso de alias puede resultarte útil si:

Conoces tu esquema y la mayoría de sus propiedades o tipos anidados
Almacenas tus datos en tipos Map
Almacenas JSON como cadenas
A menudo aplicas funciones para transformar las columnas que seleccionas

Columnas ALIAS definidas en la tabla

ClickHouse admite alias de columna de forma nativa y funciona con Grafana desde el primer momento. Las columnas alias pueden definirse directamente en la tabla.

CREATE TABLE alias_example (
  TimestampNanos DateTime(9),
  TimestampDate ALIAS toDate(TimestampNanos)
)

En el ejemplo anterior, creamos un alias llamado TimestampDate que convierte la marca de tiempo en nanosegundos al tipo Date. Estos datos no se almacenan en disco como la primera columna, sino que se calculan en tiempo de consulta. Los alias definidos en la tabla no se incluyen en SELECT *, pero esto se puede configurar en la configuración del servidor. Para obtener más información, consulta la documentación del tipo de columna ALIAS.

Tablas de alias de columnas

De forma predeterminada, Grafana ofrecerá sugerencias de columnas basadas en la respuesta de DESC table. En algunos casos, puede que quieras sustituir por completo las columnas que Grafana ve. Esto ayuda a ocultar tu esquema en Grafana al seleccionar columnas, lo que puede mejorar la experiencia de usuario en función de la complejidad de tu tabla. La ventaja de esto frente a los alias definidos en la tabla es que puedes actualizarlos fácilmente sin tener que modificarla. En algunos esquemas, esto puede llegar a tener miles de entradas, lo que puede recargar la definición de la tabla subyacente. También permite ocultar columnas que quieres que el usuario ignore. Grafana requiere que la tabla de alias tenga la siguiente estructura de columnas:

CREATE TABLE aliases (
  `alias` String,  -- The name of the alias, as seen in the Grafana column selector
  `select` String, -- The SELECT syntax to use in the SQL generator
  `type` String    -- The type of the resulting column, so the plugin can modify the UI options to match the data type.
)

Así podríamos replicar el comportamiento de la columna ALIAS usando la tabla de alias:

CREATE TABLE example_table (
  TimestampNanos DateTime(9)
);

CREATE TABLE example_table_aliases (`alias` String, `select` String, `type` String);

INSERT INTO example_table_aliases (`alias`, `select`, `type`) VALUES
('TimestampNanos', 'TimestampNanos', 'DateTime(9)'), -- Preserve original column from table (optional)
('TimestampDate', 'toDate(TimestampNanos)', 'Date'); -- Add new column that converts TimestampNanos to a Date

Luego podemos configurar esta tabla para usarla en Grafana. Ten en cuenta que el nombre puede ser cualquiera, o incluso definirse en una base de datos independiente: Ahora Grafana verá los resultados de la tabla de alias en lugar de los resultados de DESC example_table: Ambos tipos de alias pueden usarse para realizar conversiones de tipos complejas o extraer campos JSON.

Todas las opciones de YAML

Estas son todas las opciones de configuración en YAML que ofrece el plugin. Algunos campos incluyen valores de ejemplo, mientras que otros simplemente muestran el tipo de campo. Consulta la documentación de Grafana para obtener más información sobre el aprovisionamiento de fuentes de datos con YAML.

datasources:
  - name: Example ClickHouse
    uid: clickhouse-example
    type: grafana-clickhouse-datasource
    jsonData:
      host: 127.0.0.1
      port: 9000
      protocol: native
      secure: false
      username: default
      tlsSkipVerify: <boolean>
      tlsAuth: <boolean>
      tlsAuthWithCACert: <boolean>
      defaultDatabase: default
      defaultTable: <string>
      dialTimeout: 10
      queryTimeout: 60
      validateSql: false
      httpHeaders:
      - name: X-Example-Plain-Header
        value: plain text value
        secure: false
      - name: X-Example-Secure-Header
        secure: true
      logs:
        defaultDatabase: default
        defaultTable: otel_logs
        otelEnabled: false
        otelVersion: latest
        showLogLinks: <boolean>
        timeColumn: <string>
        levelColumn: <string>
        messageColumn: <string>
      traces:
        defaultDatabase: default
        defaultTable: otel_traces
        otelEnabled: false
        otelVersion: latest
        showTraceLinks: <boolean>
        traceIdColumn: <string>
        spanIdColumn: <string>
        operationNameColumn: <string>
        parentSpanIdColumn: <string>
        serviceNameColumn: <string>
        durationTimeColumn: <string>
        durationUnitColumn: <time unit>
        startTimeColumn: <string>
        tagsColumn: <string>
        serviceTagsColumn: <string>
    secureJsonData:
      tlsCACert:     <string>
      tlsClientCert: <string>
      tlsClientKey:  <string>
      secureHttpHeaders.X-Example-Secure-Header: secure header value

Fuentes de datos

Visualización de datos

Ingestión de datos

Integraciones de datos

Clientes SQL

Herramientas

Configurar la fuente de datos ClickHouse en Grafana

Configuración común

Protocolo HTTP

Ruta HTTP

Encabezados HTTP personalizados

Ajustes adicionales

OpenTelemetry

Logs

Desactivación de los enlaces «Ver logs»

Trazas

Desactivar los enlaces “Ver traza”

Alias de columnas

Columnas ALIAS definidas en la tabla

Tablas de alias de columnas

Todas las opciones de YAML

​Configuración común

​Protocolo HTTP

​Ruta HTTP

​Encabezados HTTP personalizados

​Ajustes adicionales

​OpenTelemetry

​Logs

​Desactivación de los enlaces «Ver logs»

​Trazas

​Desactivar los enlaces “Ver traza”

​Alias de columnas

​Columnas ALIAS definidas en la tabla

​Tablas de alias de columnas

​Todas las opciones de YAML

Configuración común

Protocolo HTTP

Ruta HTTP

Encabezados HTTP personalizados

Ajustes adicionales

OpenTelemetry

Logs

Desactivación de los enlaces «Ver logs»

Trazas

Desactivar los enlaces “Ver traza”

Alias de columnas

Columnas ALIAS definidas en la tabla

Tablas de alias de columnas

Todas las opciones de YAML