تهيئة مصدر بيانات ClickHouse في Grafana

خيارات التهيئة للمكون الإضافي لمصدر بيانات ClickHouse في Grafana

أسهل طريقة لتعديل الإعدادات هي عبر واجهة المستخدم في Grafana من صفحة إعدادات المكوّن الإضافي، ولكن يمكن أيضًا تهيئة مصادر البيانات باستخدام ملف YAML.

تعرض هذه الصفحة قائمة بالخيارات المتاحة لتهيئة المكوّن الإضافي ClickHouse، بالإضافة إلى مقتطفات إعدادات لمن يهيّئون مصدر بيانات باستخدام YAML.

للحصول على نظرة عامة سريعة على جميع الخيارات، يمكن العثور على قائمة كاملة بخيارات الإعداد هنا.

​

الإعدادات الشائعة

مثال على شاشة التهيئة:

مثال على ملف YAML للإعدادات الشائعة:

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

لاحظ أنه تُضاف خاصية version عند حفظ التهيئة من واجهة المستخدم. ويُظهر ذلك إصدار المكوّن الإضافي الذي حُفظت به التهيئة.

​

بروتوكول HTTP

ستظهر إعدادات إضافية إذا اخترت الاتصال عبر بروتوكول HTTP.

​

مسار HTTP

إذا كان خادم HTTP لديك مُتاحًا ضمن مسار URL مختلف، يمكنك إضافته هنا.

jsonData:
  # excludes first slash
  path: additional/path/example

​

رؤوس HTTP مخصّصة

يمكنك إضافة رؤوس مخصّصة إلى الطلبات المُرسلة إلى الخادم لديك.

يمكن أن تكون الرؤوس نصًا عاديًا أو آمنة. تُخزَّن جميع مفاتيح الرؤوس كنص عادي، بينما تُحفَظ قيم الرؤوس الآمنة في التهيئة الآمنة (على غرار الحقل password).

القيم الآمنة عبر HTTP

رغم أن قيم الرؤوس الآمنة تُخزَّن بأمان في التهيئة، فإن القيمة ستظل تُرسَل عبر HTTP إذا كان الاتصال الآمن معطّلًا.

مثال YAML للرؤوس العادية/الآمنة:

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

​

إعدادات إضافية

هذه الإعدادات الإضافية اختيارية.

مثال YAML:

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) مدمجًا بشكل وثيق في المكوّن الإضافي. يمكن تصدير بيانات OpenTelemetry إلى ClickHouse باستخدام مكوّن إضافي للمُصدِّر الخاصة بنا. ولتحقيق أفضل استفادة، يُوصى بتهيئة OTel لكلٍّ من السجلات والتتبعات.

ويجب أيضًا تهيئة هذه الإعدادات الافتراضية لتمكين روابط البيانات، وهي ميزة تتيح مسارات عمل observability قوية.

​

السجلات

لتسريع إنشاء استعلامات السجلات، يمكنك تعيين قاعدة بيانات/جدول افتراضي، بالإضافة إلى أعمدة لاستعلام السجلات. سيؤدي ذلك إلى تحميل منشئ الاستعلام مسبقًا باستعلام سجلات جاهز للتشغيل، مما يجعل التصفح في صفحة Explore أسرع لسيناريوهات observability.

إذا كنت تستخدم OpenTelemetry، فينبغي تفعيل مفتاح “Use OTel”، وتعيين جدول السجلات الافتراضي إلى otel_logs. وسيؤدي ذلك تلقائيًا إلى تجاوز الأعمدة الافتراضية لاستخدام إصدار مخطط OTel المحدد.

مع أن OpenTelemetry ليس مطلوبًا للسجلات، فإن استخدام مجموعة بيانات واحدة للسجلات/التتبعات يساعد في توفير سير عمل أكثر سلاسة لـ observability باستخدام رابط البيانات.

مثال على شاشة تهيئة السجلات:

مثال على YAML لتهيئة السجلات:

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.

​

تعطيل روابط “View logs”

يتضمن قسم ربط معرّف التتبّع في تهيئة السجلات مفتاح التبديل إظهار روابط “View logs”. يتحكم هذا المفتاح في ما إذا كان المكوّن الإضافي تُرفق روابط “View logs” لروابط البيانات بحقول معرّف التتبّع في نتائج الاستعلام. يكون مفتاح التبديل مفعّلًا افتراضيًا. لا يتطلب رابط “View logs” لنوع الاستعلام نفسه إعدادات افتراضية للسجلات، بينما يتطلبها رابط “View logs” متعدد الإشارات من نتائج استعلامات التتبّع. أوقف مفتاح التبديل، أو اضبط showLogLinks: false في YAML لإخفائها.

​

التتبعات

لتسريع إنشاء الاستعلامات للتتبعات، يمكنك تعيين قاعدة بيانات/جدول افتراضيين، بالإضافة إلى الأعمدة الخاصة باستعلام التتبع. سيؤدي ذلك إلى التحميل المسبق لمنشئ الاستعلام باستعلام بحث عن تتبع قابل للتشغيل، مما يسرّع التصفح في صفحة Explore لأغراض observability.

إذا كنت تستخدم OpenTelemetry، فيجب تفعيل مفتاح “Use OTel”، وتعيين جدول التتبع الافتراضي إلى otel_traces. وسيؤدي ذلك تلقائيًا إلى تجاوز الأعمدة الافتراضية لاستخدام إصدار مخطط OTel المحدد. ورغم أن OpenTelemetry ليس مطلوبًا، فإن هذه الميزة تعمل بأفضل شكل عند استخدام مخططه للتتبعات.

مثال على شاشة تهيئة التتبعات:

مثال على YAML لتهيئة التتبعات:

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.

​

تعطيل روابط “View trace”

يحتوي قسم ربط معرّف التتبّع في تهيئة التتبعات على مفتاح التبديل إظهار روابط “View trace”. يتحكم هذا المفتاح في إرفاق المكوّن الإضافي لروابط “View trace” من روابط البيانات بحقول معرّف التتبّع في نتائج الاستعلامات. يكون مفتاح التبديل مفعّلًا افتراضيًا. لا يتطلب رابط “View trace” للاستعلام من النوع نفسه إعدادات تتبّع افتراضية، بينما يتطلبها رابط “View trace” متعدد الإشارات من نتائج استعلامات السجلات. أوقف مفتاح التبديل، أو اضبط showTraceLinks: false في YAML، لإخفائها.

​

الأسماء المستعارة للأعمدة

يُعدّ استخدام الأسماء المستعارة للأعمدة طريقةً عملية للاستعلام عن بياناتك بأسماء وأنواع مختلفة. وباستخدام الأسماء المستعارة، يمكنك تحويل مخطط متداخل إلى مخطط مسطّح بحيث يسهل اختياره في Grafana.

قد يكون استخدام الأسماء المستعارة مناسبًا لك إذا كنت:

• تعرف مخطط بياناتك ومعظم خصائصه/أنواعه المتداخلة
• تخزّن بياناتك في أنواع Map
• تخزّن JSON كسلاسل نصية
• تطبّق كثيرًا دوالًا لتحويل الأعمدة التي تختارها

​

أعمدة ALIAS المعرّفة على الجدول

يوفّر ClickHouse دعمًا مدمجًا للأسماء المستعارة للأعمدة، ويعمل مع Grafana مباشرةً. يمكن تعريف أعمدة ALIAS مباشرةً على الجدول.

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

في المثال أعلاه، ننشئ اسمًا مستعارًا باسم TimestampDate يحوّل الطابع الزمني بالنانوثانية إلى النوع Date. ولا تُخزَّن هذه البيانات على القرص مثل العمود الأول، بل تُحتسَب وقت تنفيذ الاستعلام. لن تُعاد الأسماء المستعارة المعرّفة على الجدول مع SELECT *، لكن يمكن ضبط ذلك في إعدادات الخادم.

لمزيد من المعلومات، اطّلع على وثائق نوع العمود ALIAS.

​

جداول الأسماء المستعارة للأعمدة

يوفّر Grafana، افتراضيًا، اقتراحات للأعمدة استنادًا إلى الاستجابة من DESC table. في بعض الحالات، قد ترغب في تجاوز الأعمدة التي يراها Grafana بالكامل. يساعد ذلك على إخفاء مخططك في Grafana عند اختيار الأعمدة، مما قد يحسّن تجربة المستخدم بحسب مدى تعقيد جدولك.

وتتمثل ميزة هذا الأسلوب مقارنةً بالأسماء المستعارة المعرّفة على مستوى الجدول في أنه يمكنك تحديثها بسهولة من دون الحاجة إلى تعديل جدولك. وفي بعض المخططات، قد يصل ذلك إلى آلاف الإدخالات، مما قد يكدّس تعريف الجدول الأساسي. كما يتيح لك إخفاء الأعمدة التي تريد من المستخدم تجاهلها.

يتطلب Grafana أن يحتوي جدول الأسماء المستعارة على بنية الأعمدة التالية:

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

إليك كيف يمكننا محاكاة سلوك العمود ALIAS باستخدام جدول 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

يمكننا بعد ذلك إعداد هذا الجدول لاستخدامه في Grafana. لاحظ أن الاسم يمكن أن يكون أي اسم، أو حتى يمكن تعريفه في قاعدة بيانات منفصلة:

سيعرض Grafana الآن نتائج جدول الأسماء المستعارة بدلًا من النتائج الناتجة عن DESC example_table:

يمكن استخدام كلا نوعَي الأسماء المستعارة لإجراء تحويلات معقدة للأنواع أو لاستخراج حقول JSON.

​

جميع خيارات YAML

فيما يلي جميع خيارات تهيئة YAML التي يوفّرها المكوّن الإضافي. تتضمن بعض الحقول قيمًا نموذجية، بينما يكتفي بعضها الآخر بعرض نوع الحقل.

راجع وثائق Grafana لمزيد من المعلومات حول تهيئة مصادر البيانات باستخدام 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