Premiers pas avec Managed ClickStack

Depuis votre service ClickHouse Cloud, lancez ClickStack. Sur la page Premiers pas de ClickStack, sélectionnez Commencer l’ingestion.

Sur la page Choisir une source d’ingestion, sélectionnez OpenTelemetry.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON default.* TO `clickstack-ingest`;

docker run -e CLICKHOUSE_ENDPOINT="https://<host>:8443" \
    -e CLICKHOUSE_USER="default" \
    -e CLICKHOUSE_PASSWORD="<your_password_here>" \
    -p 4317:4317 -p 4318:4318 \
    clickhouse/clickstack-otel-collector:latest

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

Envoyez un log de test avec l’horodatage actuel :

NOW_NANO="$(date +%s)000000000"

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "${NOW_NANO}",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF

Si vous utilisez un collector existant, remplacez http://localhost:4318 par son endpoint HTTP OTLP. Si le receiver nécessite une authentification, ajoutez le header obligatoire à la commande curl.

Une requête réussie renvoie HTTP/1.1 200 OK.

Une fois que ClickStack a détecté les sources de données OpenTelemetry, sélectionnez Start exploring pour ouvrir la vue Search. Recherchez ClickStack ingestion test.

Le résultat doit inclure l’événement de test dont le nom de service est clickstack-docs-test.

Depuis votre service ClickHouse Cloud, lancez ClickStack. Sur la page Getting Started de ClickStack, sélectionnez Start ingestion.

Sur la page Choose an ingestion source, sélectionnez Vector.

Vector est un pipeline de données d'observabilité haute performance et indépendant de tout fournisseur, particulièrement apprécié pour l'ingestion de logs grâce à sa flexibilité et à sa faible empreinte sur les ressources.

Lorsque vous utilisez Vector avec ClickStack, c'est vous qui définissez le schéma. Celui-ci peut respecter les conventions OpenTelemetry ou utiliser des champs propres à vos événements.

Créer une database et une table

Créez une database et une table avant de configurer le sink Vector.

Dans ClickHouse Cloud, ouvrez la SQL Console de votre service et créez une database :

Par exemple, créez une database pour les logs :

CREATE DATABASE IF NOT EXISTS logs

Créez ensuite une table dont le schema correspond à la structure de vos données de logs. L'exemple ci-dessous part du principe qu'il s'agit d'un log format d'accès Nginx classique :

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);

Votre table doit correspondre au schema de sortie produit par Vector. Adaptez le schema à vos données, en suivant les bonnes pratiques de schema recommandées.

Nous recommandons vivement de bien comprendre le fonctionnement des clés primaires dans ClickHouse et de choisir une clé de tri adaptée à vos modèles d'accès. Consultez les recommandations spécifiques à ClickStack sur le choix d'une clé primaire.

Configurer le sink ClickHouse

Une fois la table créée, ajoutez un sink ClickHouse à votre configuration Vector :

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "https://<host>:8443"
    database: logs
    table: nginx_logs
    format: json_each_row
    skip_unknown_fields: true
    auth:
      strategy: basic
      user: default
      password: "<your_password_here>"

Remplacez your_input par l'entrée de votre pipeline existant. Remplacez <host> et <your_password_here> par les valeurs correspondant à votre service ClickHouse Cloud. Si nécessaire, modifiez la base de données ou la table cible.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT ON logs.nginx_logs TO `clickstack-ingest`;

Enregistrez la configuration mise à jour, puis rechargez ou redémarrez Vector à l'aide de votre processus de déploiement existant.

Pour d'autres exemples d'ingestion de données avec Vector, consultez Ingestion avec Vector ou la documentation du sink ClickHouse de Vector pour les options avancées.

Créer une source de données ClickStack

Créez une data source pour la table alimentée par votre pipeline Vector. ClickStack vous invite à en créer une lors de votre première connexion.

Le formulaire préremplit les expressions correspondant au schéma OpenTelemetry par défaut. Pour la table Nginx créée dans ce guide, configurez la source avec les valeurs suivantes :

La table Nginx ne contient pas de colonne Body. Définissez Body Expression sur :

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%i:%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, '"'
)

Pour les autres paramètres de source, consultez la référence de configuration ClickStack.

Envoyez un événement représentatif à l’entrée de votre pipeline Vector existant.

Pour d’autres exemples de sources et de transformations Vector, consultez Ingestion avec Vector.

Après avoir créé la source de données, sélectionnez Start exploring pour ouvrir la vue Search. Sélectionnez la source de données associée à votre table et vérifiez qu’elle contient l’événement envoyé.