[Документация Yandex Cloud](../../index.md) > [Практические руководства](../index.md) > Анализ и визуализация данных > Аналитика > Визуализация логов в Grafana с помощью плагина Cloud Logging

# Визуализация логов в Grafana с помощью плагина Yandex Cloud Logging


{% note warning %}

Часть ресурсов, необходимых для прохождения практического руководства, доступны только в [регионе Россия](../../overview/concepts/region.md).

{% endnote %}

{% note info %}

В [регионе Казахстан](../../overview/concepts/region.md) доступна только [зона доступности](../../overview/concepts/geo-scope.md) `kz1-a`.

{% endnote %}


[Плагин Yandex Cloud Logging для Grafana](https://github.com/yandex-cloud/grafana-logs-plugin/tree/master) — расширение для Grafana, с помощью которого можно добавить [Cloud Logging](https://yandex.cloud/ru/services/logging) в качестве источника данных.

{% note info %}

Плагин Cloud Logging работает с Grafana версии 11.2.0 и ниже. В разных версиях названия меню и элементы интерфейса могут отличаться.

{% endnote %}

Чтобы визуализировать логи:

1. [Установите плагин](#install-plugin).
1. [Создайте сервисный аккаунт](#create-account).
1. [Создайте авторизованный ключ для сервисного аккаунта](#create-key).
1. [Создайте лог-группу](#create-group).
1. [Добавьте записи в лог-группу](#add-records).
1. [Подключите источник данных в Grafana](#connect-plugin).
1. [Посмотрите логи в Grafana](#see-logs).

Если созданные ресурсы вам больше не нужны, [удалите их](#clear-out).

## Подготовьте облако к работе {#before-begin}

Зарегистрируйтесь в Yandex Cloud и создайте [платежный аккаунт](../../billing/concepts/billing-account.md):
1. Перейдите в [консоль управления](https://kz.console.yandex.cloud), затем войдите в Yandex Cloud или зарегистрируйтесь.
1. На странице **[Yandex Cloud Billing](https://kz.console.yandex.cloud/billing)** убедитесь, что у вас подключен платежный аккаунт, и он находится в [статусе](../../billing/concepts/billing-account-statuses.md) `ACTIVE` или `TRIAL_ACTIVE`. Если платежного аккаунта нет, [создайте его](../../billing/quickstart/index.md) и [привяжите](../../billing/operations/pin-cloud.md) к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать [каталог](../../resource-manager/concepts/resources-hierarchy.md#folder), в котором будет работать ваша инфраструктура, на [странице облака](https://kz.console.yandex.cloud/cloud).

[Подробнее об облаках и каталогах](../../resource-manager/concepts/resources-hierarchy.md).

### Необходимые платные ресурсы {#paid-resources}

В стоимость ресурсов входит плата за запись и хранение логов в лог-группе ([тарифы Yandex Cloud Logging](../../logging/pricing.md)).

## Установите плагин {#install-plugin}

1. [Скачайте](https://github.com/yandex-cloud/grafana-logs-plugin/releases) архив с последней версией плагина.
1. Распакуйте архив в папку с плагинами. Расположение папки с плагинами указывается в [конфигурации Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/).

   ```bash
   unzip <путь_к_архиву> -d <путь_к_папке_с_плагинами>
   ```

   {% note info %}

   Если вы используете macOS, после распаковки плагина вручную запустите файл `/opt/homebrew/var/lib/grafana/plugins/yandexcloud-logging-datasource/yc-logs-plugin_darwin_arm64` и в системных настройках [разрешите запуск приложений от сторонних разработчиков](https://support.apple.com/ru-ru/HT202491#openanyway).

   {% endnote %}

1. Разрешите загрузку плагина без подписи. Для этого в конфигурационном файле Grafana укажите название плагина в параметре `allow_loading_unsigned_plugins`:

   ```text
   allow_loading_unsigned_plugins = yandexcloud-logging-datasource
   ```

   Подробнее о загрузке плагинов без подписи смотрите в [документации Grafana](https://grafana.com/docs/grafana/latest/administration/plugin-management/#allow-unsigned-plugins).

1. Перезапустите сервер Grafana:

   {% list tabs group=operating_system %}

   - Linux {#linux}

     ```bash
     sudo systemctl restart grafana-server
     ```

   - Windows {#windows}

     1. Нажмите сочетание клавиш **Win+R**.
     1. В открывшемся окне введите `services.msc` и нажмите кнопку **ОК**.
     1. Нажмите правой кнопкой мыши строку со службой `Grafana` и выберите **Перезапустить**.

   - macOS {#macos}

     ```bash
     brew services restart grafana
     ```

   {% endlist %}  

## Создайте сервисный аккаунт {#create-account}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, в котором хотите создать сервисный аккаунт.
  1. Перейдите в сервис **Identity and Access Management**.
  1. Нажмите кнопку **Создать сервисный аккаунт**.
  1. Введите имя сервисного аккаунта: `grafana-plugin`.
  1. Нажмите **Добавить роль** и выберите роль `logging.reader`.
  1. Нажмите кнопку **Создать**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  1. Создайте сервисный аккаунт `grafana-plugin`:

     ```bash
     yc iam service-account create --name grafana-plugin
     ```

     Результат:

     ```text
     id: nfersamh4s**********
     folder_id: b1gc1t4cb6**********
     created_at: "2023-09-26T10:36:29.726397755Z"
     name: grafana-plugin
     ```

     Сохраните идентификатор сервисного аккаунта `grafana-plugin` (`id`) и каталога, в котором его создали (`folder_id`).

  1. Назначьте сервисному аккаунту роль `logging.reader` на каталог:

     ```bash
     yc resource-manager folder add-access-binding <идентификатор_каталога> \
       --role logging.reader \
       --subject serviceAccount:<идентификатор_сервисного_аккаунта>
     ```

     Результат:

     ```text
     done (1s)
     ```

- Terraform {#tf}

  
  Если у вас еще нет Terraform, [установите его и настройте провайдер Yandex Cloud](../infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  Чтобы управлять инфраструктурой с помощью Terraform от имени сервисного аккаунта или пользовательских аккаунтов: аккаунта на Яндексе, федеративного аккаунта и локального пользователя, [аутентифицируйтесь](../../terraform/authentication.md) соответствующим способом.


  1. Опишите в конфигурационном файле параметры сервисного аккаунта:

     ```hcl
     resource "yandex_iam_service_account" "grafana-plugin" {
       name        = "grafana-plugin"
       folder_id   = "<идентификатор_каталога>"
     }

     resource "yandex_resourcemanager_folder_iam_member" "reader" {
       folder_id = "<идентификатор_каталога>"
       role      = "logging.reader"
       member    = "serviceAccount:${yandex_iam_service_account.grafana-plugin id}"
     }
     ```

     Где:

     * `name` — имя сервисного аккаунта. Обязательный параметр.
     * `folder_id` — [идентификатор каталога](../../resource-manager/operations/folder/get-id.md). Необязательный параметр. По умолчанию будет использовано значение, указанное в настройках провайдера.
     * `role` — назначаемая роль.

     Подробнее о параметрах ресурса `yandex_iam_service_account` в Terraform смотрите в [документации провайдера](../../terraform/resources/iam_service_account.md).

  1. Проверьте корректность конфигурационных файлов.

     1. В командной строке перейдите в папку, где вы создали конфигурационный файл.
     1. Выполните проверку с помощью команды:

         ```bash
         terraform plan
         ```

     Если конфигурация описана верно, в терминале отобразится информация о сервисном аккаунте. Если в конфигурации есть ошибки, Terraform на них укажет.

  1. Разверните облачные ресурсы.

  1. Если в конфигурации нет ошибок, выполните команду:

     ```bash
     terraform apply
     ```

  1. Подтвердите создание сервисного аккаунта: введите в терминал слово `yes` и нажмите **Enter**.

     После этого будет создан сервисный аккаунт. Проверить появление сервисного аккаунта можно в [консоли управления](https://kz.console.yandex.cloud) или с помощью команды [CLI](../../cli/quickstart.md):

     ```bash
     yc iam service-account list
     ```

- API {#api}

  Чтобы создать сервисный аккаунт, воспользуйтесь методом [create](../../iam/api-ref/ServiceAccount/create.md) для ресурса [ServiceAccount](../../iam/api-ref/ServiceAccount/index.md) или вызовом gRPC API [ServiceAccountService/Create](../../iam/api-ref/grpc/ServiceAccount/create.md).

  Чтобы назначить сервисному аккаунту роль `logging.reader` на каталог, воспользуйтесь методом [setAccessBindings](../../iam/api-ref/ServiceAccount/setAccessBindings.md) для ресурса [ServiceAccount](../../iam/api-ref/ServiceAccount/index.md) или вызовом gRPC API [ServiceAccountService/SetAccessBindings](../../iam/api-ref/grpc/ServiceAccount/setAccessBindings.md).

{% endlist %}

## Создайте авторизованный ключ для сервисного аккаунта {#create-key}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит сервисный аккаунт.
  1. Перейдите в сервис **Identity and Access Management**.
  1. На панели слева выберите ![FaceRobot](../../_assets/console-icons/face-robot.svg) **Сервисные аккаунты**.
  1. В открывшемся списке выберите сервисный аккаунт `grafana-plugin`.
  1. Нажмите кнопку **Создать новый ключ** на верхней панели.
  1. Выберите пункт **Создать авторизованный ключ**.
  1. Выберите алгоритм шифрования.
  1. Задайте описание ключа, чтобы потом было проще найти его в консоли управления.
  1. Нажмите кнопку **Создать**.
  1. В открывшемся окне нажмите кнопку **Скачать файл с ключами**.
  1. Нажмите кнопку **Закрыть**.

- CLI {#cli}

  Создайте авторизованные ключи для сервисного аккаунта `grafana-plugin`:

  ```bash
  yc iam key create --service-account-name grafana-plugin -o authorized_key.json
  ```

  В случае успеха в файл `authorized_key.json` будет записан закрытый ключ (`privateKey`) и идентификатор открытого ключа (`id`).

  Пример файла с ключом:

  ```json
  {
     "id": "lfkoe35hsk**********",
     "service_account_id": "ajepg0mjt0**********",
     "created_at": "2023-10-10T10:04:56Z",
     "key_algorithm": "RSA_2048",
     "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
     "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  }
  ```

- Terraform {#tf}

  1. Опишите в конфигурационном файле параметры ресурсов, которые необходимо создать:

     * `service_account_id` — [идентификатор](../../iam/operations/sa/get-id.md) сервисного аккаунта. Обязательный параметр.
     * `description` — описание ключа. Необязательный параметр.
     * `key_algorithm` — алгоритм генерации ключа. Необязательный параметр. По умолчанию используется алгоритм `RSA_2048`. Допустимые значения параметра смотрите в [документации API](../../iam/api-ref/Key/index.md).

     Пример структуры конфигурационного файла:

     ```hcl
     resource "yandex_iam_service_account_key" "sa-auth-key" {
       service_account_id = "<идентификатор_сервисного_аккаунта>"
       description        = "<описание_ключа>"
       key_algorithm      = "<алгоритм_генерации_ключа>"
     }
     ```

     Подробнее о ресурсах, которые вы можете создать с помощью Terraform, смотрите в [документации провайдера](../../terraform/resources/iam_service_account_key.md).

  1. Проверьте корректность конфигурационных файлов.

     1. В командной строке перейдите в папку, где вы создали конфигурационный файл.
     1. Выполните проверку с помощью команды:

        ```bash
        terraform plan
        ```

     Если конфигурация описана верно, в терминале отобразится список создаваемых ресурсов и их параметров. Если в конфигурации есть ошибки, Terraform на них укажет.

  1. Разверните облачные ресурсы.

     1. Если в конфигурации нет ошибок, выполните команду:

        ```bash
        terraform apply
        ```

     1. Подтвердите создание ресурсов: введите в терминал слово `yes` и нажмите **Enter**.

        После этого в указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в [консоли управления](https://kz.console.yandex.cloud), а также с помощью команды CLI:

        ```bash
        yc iam key list --service-account-id <идентификатор_сервисного_аккаунта>
        ```

- API {#api}

  Чтобы создать ключ доступа, воспользуйтесь методом REST API [create](../../iam/api-ref/Key/create.md) для ресурса [Key](../../iam/api-ref/Key/index.md) или вызовом gRPC API [KeyService/Create](../../iam/api-ref/grpc/Key/create.md).

  Пример запроса с помощью cURL для метода REST API `create`:

  ```bash
  curl --request POST \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer <IAM-токен>" \
    --data '{"serviceAccountId": "<идентификатор_сервисного_аккаунта>"}' \
    https://iam.api.yandexcloud.kz/iam/v1/keys
  ```

  Где:

  * `<IAM-токен>` — IAM-токен пользователя, у которого есть права на создание ключей для указанного сервисного аккаунта.
  * `<идентификатор_сервисного_аккаунта>` — идентификатор сервисного аккаунта, для которого создаются ключи.

  В случае успеха в ответе сервера будет указан закрытый ключ (`privateKey`) и идентификатор открытого ключа (`id`). Сохраните эти данные. Получить значение ключа снова будет невозможно.

  Пример ответа сервера:

  ```json
  {
      "key": {
          "createdAt": "2023-10-10T10:55:00+00:00",
          "description": "",
          "id": "lfkoe35hsk**********",
          "keyAlgorithm": "RSA_2048",
          "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
          "serviceAccountId": "ajepg0mjt0**********"
      },
      "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  }
  ```

{% endlist %}

## Создайте лог-группу {#create-group}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) перейдите в каталог, в котором создали сервисный аккаунт `grafana-plugin`.
  1. Перейдите в сервис **Cloud Logging**.
  1. Нажмите кнопку **Создать группу**.
  1. Введите имя лог-группы: `grafana-plugin`.
  1. Укажите срок хранения записей в лог-группе.
  1. Нажмите кнопку **Создать группу**.

- CLI {#cli}

  Чтобы создать лог-группу, выполните команду:

  ```bash
  yc logging group create \
    --name=grafana-plugin \
    --retention-period=<срок_хранения> \
  ```

  Где:

  * `--name` — имя лог-группы.
  * `--retention-period` — срок хранения записей в лог-группе.

  Результат:

  ```text
  done (1s)
  id: af3flf29t8**********
  folder_id: aoek6qrs8t**********
  cloud_id: aoegtvhtp8**********
  created_at: "2023-09-26T09:56:38.970Z"
  name: grafana-plugin
  status: ACTIVE
  retention_period: 3600s
  ```

- Terraform {#tf}

  1. Опишите в конфигурационном файле параметры лог-группы:

     ```hcl
     provider "yandex" {
       cloud_id  = "<идентификатор_облака>"
       folder_id = "<идентификатор_каталога>"
       zone      = "kz1-a"
     }

     resource "yandex_logging_group" "grafana-plugin" {
       name             = "grafana-plugin"
       folder_id        = "<идентификатор_каталога>"
       retention_period = "1h"
     }
     ```

     Где:

     * `name` — имя лог-группы.
     * `folder_id` — [идентификатор каталога](../../resource-manager/operations/folder/get-id.md).
     * `retention_period` — срок хранения записей в лог-группе.

     Подробнее о параметрах ресурса `yandex_logging_group` в Terraform смотрите в [документации провайдера](../../terraform/resources/logging_group.md).

  1. Проверьте корректность конфигурационных файлов.

     1. В командной строке перейдите в папку, где вы создали конфигурационный файл.
     1. Выполните проверку с помощью команды:

        ```bash
        terraform plan
        ```

     Если конфигурация описана верно, в терминале отобразится список создаваемых ресурсов и их параметров. Если в конфигурации есть ошибки, Terraform на них укажет.

  1. Разверните облачные ресурсы.

  1. Если в конфигурации нет ошибок, выполните команду:

     ```bash
     terraform apply
     ```

  1. Подтвердите создание ресурсов: введите в терминал слово `yes` и нажмите **Enter**.

     После этого в указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в [консоли управления](https://kz.console.yandex.cloud) или с помощью команды [CLI](../../cli/quickstart.md):

     ```bash
     yc logging group list
     ```

- API {#api}

  Чтобы создать лог-группу, воспользуйтесь методом REST API [create](../../logging/api-ref/LogGroup/create.md) для ресурса [LogGroup](../../logging/api-ref/LogGroup/index.md) или вызовом gRPC API [LogGroupService/Create](../../logging/api-ref/grpc/LogGroup/create.md).

{% endlist %}

## Добавьте записи в лог-группу {#add-records}

{% list tabs group=instructions %}

- CLI {#cli}

  Чтобы добавить записи в лог-группу, выполните команду:

  * Linux, macOS:

    ```bash
    yc logging write \
      --group-name=grafana-plugin \
      --message="My message" \
      --level=INFO
    ```

  * Windows (cmd):

    ```bash
    yc logging write ^
      --group-name=grafana-plugin ^
      --message="My message" ^
      --level=INFO
    ```

  * Windows (PowerShell):

    ```bash
    yc logging write `
      --group-name=grafana-plugin `
      --message="My message" `
      --level=INFO
    ```

    Где:

    * `--group-name` — имя лог-группы, в которую вы хотите добавить записи.
    * `--message` — сообщение.
    * `--level` — уровень логирования.

   {% note info %}

   Параметры `--group-name` и `--message` можно опустить и указать только значения параметров. Например: `grafana-plugin "My message"`.

   {% endnote %}

- API {#api}

  Чтобы добавить записи в лог-группу, воспользуйтесь вызовом gRPC API [LogIngestionService/Write](../../logging/api-ref/grpc/LogIngestion/write.md).

{% endlist %}

## Подключите источник данных в Grafana {#connect-plugin}

1. В браузере перейдите по адресу `http://localhost:3000/`.

   {% note info %}

   По умолчанию Grafana использует порт 3000, если в конфигурационном файле вы не [указали другой](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#http_port).

   {% endnote %}

1. На панели слева выберите **Connections** → **Add new connection**.
1. В списке источников выберите **Yandex Cloud Logging**.
1. Нажмите кнопку **Add new data source**.
1. В блоке **Secret config**, в поле **API Key**, вставьте содержимое файла с [авторизованными ключами](#create-key) `authorized_key.json`.
1. В блоке **SDK config**, в поле **Folder ID**, укажите идентификатор каталога, в котором находится лог-группа `grafana-plugin`.
1. Нажмите кнопку **Save & test**.

## Посмотрите логи в Grafana {#see-logs}

1. В интерфейсе Grafana на панели слева выберите **Explore**.
1. В левом верхнем углу выберите из выпадающего списка источник данных **Yandex Cloud Logging**.
1. В редакторе запросов для источника:

   1. В поле **Group** выберите идентификатор лог-группы `grafana-plugin`.
   1. В поле **Filter query** введите запрос на [языке фильтрующих выражений](../../logging/concepts/filter.md).
   1. В правом верхнем углу нажмите кнопку **Run query**.

      В блоке **Logs volume** отобразится гистограмма с записями из лог-группы.

## Как удалить созданные ресурсы {#clear-out}

Чтобы перестать платить за созданные ресурсы, [удалите лог-группу](../../logging/operations/delete-group.md).