Плагин Google Cloud экспортирует данные телеметрии и журналирования Firebase Genkit в пакет Cloud Observability .
Установка
npm i --save @genkit-ai/google-cloudПри локальном запуске кода Genkit, включающего этот плагин, вам также потребуется установить инструмент Google Cloud CLI .
Настройте учетную запись Google Cloud
Для этого плагина требуется учетная запись/проект Google Cloud. Все проекты Firebase включают одну из них по умолчанию ( консоль GCP ), или вы можете зарегистрироваться на https://cloud.google.com.
Прежде чем добавлять плагин, убедитесь, что для вашего проекта GCP включены следующие API:
Эти API должны быть перечислены на панели управления API вашего проекта.
Нажмите здесь, чтобы узнать больше о включении и отключении API.
Конфигурация генкита
Чтобы включить облачную трассировку, ведение журнала и мониторинг (метрики), просто вызовите enableGoogleCloudTelemetry() :
import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
enableGoogleCloudTelemetry();
При запуске в рабочей среде телеметрия будет экспортироваться автоматически.
Аутентификация и авторизация
Для плагина требуется идентификатор проекта Google Cloud и учетные данные приложения.
Google Облако
При развертывании вашего кода в облачной среде Google (Cloud Functions, Cloud Run и т. д.) идентификатор проекта и учетные данные будут обнаружены автоматически с помощью учетных данных приложения по умолчанию .
Вам нужно будет применить следующие роли к учетной записи службы, на которой выполняется ваш код (т. е. «подключенная учетная запись службы») через консоль IAM :
-
roles/monitoring.metricWriter -
roles/cloudtrace.agent -
roles/logging.logWriter
Местное развитие
При локальной разработке для того, чтобы ваши учетные данные пользователя были доступны плагину, требуются дополнительные шаги.
Установите переменную среды
GCLOUD_PROJECTдля вашего проекта Google Cloud.Аутентификация с помощью интерфейса командной строки
gcloud:gcloud auth application-default login
Производственные среды за пределами Google Cloud
Если возможно, по-прежнему рекомендуется использовать процесс учетных данных приложения по умолчанию, чтобы сделать учетные данные доступными для плагина.
Обычно это включает в себя создание ключа/пары служебной учетной записи и развертывание этих учетных данных в вашей производственной среде.
Следуйте инструкциям, чтобы настроить ключ учетной записи службы .
Убедитесь, что учетная запись службы имеет следующие роли:
-
roles/monitoring.metricWriter -
roles/cloudtrace.agent -
roles/logging.logWriter
-
Разверните файл учетных данных в рабочей среде ( не проверяйте исходный код).
Задайте переменную среды
GOOGLE_APPLICATION_CREDENTIALSв качестве пути к файлу учетных данных.GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
В некоторых бессерверных средах развернуть файл учетных данных может оказаться невозможным. В этом случае в качестве альтернативы шагам 3 и 4, описанным выше, вы можете установить переменную среды GCLOUD_SERVICE_ACCOUNT_CREDS с содержимым файла учетных данных следующим образом:
GCLOUD_SERVICE_ACCOUNT_CREDS='{
"type": "service_account",
"project_id": "your-project-id",
"private_key_id": "your-private-key-id",
"private_key": "your-private-key",
"client_email": "your-client-email",
"client_id": "your-client-id",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "your-cert-url"
}'
Конфигурация плагина
Функция enableGoogleCloudTelemetry() принимает дополнительный объект конфигурации, который настраивает экземпляр OpenTelemetry NodeSDK .
import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';
enableGoogleCloudTelemetry({
forceDevExport: false, // Set this to true to export telemetry for local runs
sampler: new AlwaysOnSampler(),
autoInstrumentation: true,
autoInstrumentationConfig: {
'@opentelemetry/instrumentation-fs': { enabled: false },
'@opentelemetry/instrumentation-dns': { enabled: false },
'@opentelemetry/instrumentation-net': { enabled: false },
},
metricExportIntervalMillis: 5_000,
});
Объекты конфигурации обеспечивают детальный контроль над различными аспектами экспорта телеметрии, описанными ниже.
реквизиты для входа
Позволяет указывать учетные данные напрямую с помощью JWTInput из библиотеки Google-auth.
пробоотборник
В случаях, когда экспорт всех трассировок нецелесообразен, OpenTelemetry позволяет осуществлять выборку трассировок.
Существует четыре предварительно настроенных семплера:
- AlwaysOnSampler — выборка всех трассировок
- AlwaysOffSampler — сэмплирует без следов
- ParentBased — образцы на основе родительского диапазона.
- TraceIdRatioBased — выборка настраиваемого процента трассировок.
autoInstrumentation и autoInstrumentationConfig
Включение автоматического инструментирования позволяет OpenTelemetry собирать данные телеметрии из сторонних библиотек без необходимости изменения кода.
metricExportIntervalMillis
В этом поле указывается интервал экспорта метрик в миллисекундах.
metricExportTimeoutMillis
В этом поле указывается время ожидания экспорта метрик в миллисекундах.
отключить метрику
Предоставляет переопределение, которое отключает экспорт метрик, сохраняя при этом экспорт трассировок и журналов.
отключитьследы
Предоставляет переопределение, которое отключает экспорт трассировок, сохраняя при этом метрики и журналы.
отключить логгингинпутандаутпут
Предоставляет переопределение, которое отключает сбор журналов ввода и вывода.
ForceDevExport
Эта опция заставит Genkit экспортировать данные телеметрии и журналов при работе в среде dev (например, локально).
Проверьте свою интеграцию
При настройке плагина используйте forceDevExport: true , чтобы включить экспорт телеметрии для локальных запусков. Перейдите к журналам Google Cloud, метрикам или Trace Explorer, чтобы просмотреть телеметрию.
Пакет Google Cloud Observability
После развертывания вашего кода (например, потока) перейдите на панель мониторинга Cloud Monitoring и выберите свой проект. Отсюда вы можете легко перемещаться между обозревателями журналов, метрик и трассировки для мониторинга производства.
Журналы и трассировки
В меню слева нажмите «Обозреватель журналов» под заголовком «Обзор».
Здесь вы увидите все журналы, связанные с развернутым вами кодом Genkit, включая console.log() . Любой журнал с префиксом [genkit] является внутренним журналом Genkit и содержит информацию, которая может быть интересна для целей отладки. Например, журналы Genkit в формате Config[...] содержат метаданные, такие как значения температуры и topK для конкретных выводов LLM. Журналы в формате Output[...] содержат ответы LLM, а журналы Input[...] содержат подсказки. Cloud Logging имеет надежные списки управления доступом, которые обеспечивают детальный контроль доступа к конфиденциальным журналам.
Откроется панель предварительного просмотра трассировки, на которой можно быстро просмотреть детали трассировки. Чтобы просмотреть полную информацию, нажмите ссылку «Просмотреть в трассировке» в правом верхнем углу панели.
Наиболее заметным элементом навигации в Cloud Trace является диаграмма рассеяния трассировки. Он содержит все собранные трассировки за определенный промежуток времени.
Нажатие на каждую точку данных покажет ее подробную информацию под диаграммой рассеяния.
Подробное представление содержит форму потока, включая все этапы, а также важную информацию о времени. Cloud Trace имеет возможность чередовать все журналы, связанные с данной трассировкой, в этом представлении. В раскрывающемся списке «Журналы и события» выберите параметр «Показать развернуто».
Полученное представление позволяет детально изучить журналы в контексте трассировки, включая запросы и ответы LLM.
Метрики
Просмотреть все метрики, экспортированные Genkit, можно, нажав «Управление метриками» под заголовком «Настроить» в меню слева.
Консоль управления метриками содержит табличное представление всех собранных метрик, включая те, которые относятся к Cloud Run и окружающей среде. При нажатии на опцию «Рабочая нагрузка» откроется список, включающий метрики, собранные Genkit. Любая метрика с префиксом genkit представляет собой внутреннюю метрику Genkit.
Genkit собирает несколько категорий показателей, включая: функцию, действие и генерацию. Каждая метрика имеет несколько полезных измерений, облегчающих надежную фильтрацию и группировку.
Общие размеры включают в себя:
-
flow_name— имя потока верхнего уровня. -
flow_path— диапазон и его родительский диапазон до корневого диапазона. -
error_code— в случае ошибки соответствующий код ошибки. -
error_message— в случае ошибки соответствующее сообщение об ошибке. -
model- название модели.
Метрики функций
Функции — это точка входа верхнего уровня в ваш код Genkit. В большинстве случаев это будет поток. В противном случае это будет самый верхний диапазон трассировки.
| Имя | Тип | Описание |
|---|---|---|
| генкит/функция/запросы | Прилавок | Количество запросов |
| генкит/функция/задержка | Гистограмма | Задержка выполнения в мс |
Каждая метрика функции содержит следующие измерения:
| Имя | Описание |
|---|---|
| имя | Название функции. В большинстве случаев это поток Genkit верхнего уровня. |
| статус | «успех» или «неудача» в зависимости от того, был ли успешен запрос функции. |
| ошибка | Устанавливается только тогда, когда status=failure . Содержит тип ошибки, вызвавшей сбой. |
| источник | Исходный язык Genkit. Например. 'тс' |
| исходная версия | Версия платформы Genkit |
Метрики действий
Действия представляют собой общий этап выполнения в Genkit. На каждом из этих шагов будут отслеживаться следующие показатели:
| Имя | Тип | Описание |
|---|---|---|
| генкит/действие/запросы | Прилавок | Сколько раз это действие было выполнено |
| генкит/действие/задержка | Гистограмма | Задержка выполнения в мс |
Каждая метрика действия содержит следующие измерения:
| Имя | Описание |
|---|---|
| имя | Название действия |
| имя_функции | Имя выполняемого родительского объекта |
| путь | Путь выполнения от корня функции до этого действия. например. '/myFeature/parentAction/thisAction' |
| статус | «успех» или «неудача» в зависимости от того, удалось ли действие |
| ошибка | Устанавливается только тогда, когда status=failure . Содержит тип ошибки, вызвавшей сбой. |
| источник | Исходный язык Genkit. Например. 'тс' |
| исходная версия | Версия платформы Genkit |
Генерация показателей
Это специальные метрики действий, относящиеся к действиям, которые взаимодействуют с моделью. Помимо запросов и задержки, также отслеживаются входные и выходные данные с учетом конкретных параметров модели, которые упрощают отладку и настройку конфигурации.
| Имя | Тип | Описание |
|---|---|---|
| genkit/ai/генерировать/запросы | Прилавок | Сколько раз вызывалась эта модель |
| genkit/ai/генерировать/задержку | Гистограмма | Задержка выполнения в мс |
| genkit/ai/генерировать/ввод/токены | Прилавок | Входные токены |
| genkit/ai/генерировать/вывод/токены | Прилавок | Выходные токены |
| genkit/ai/генерировать/ввод/символы | Прилавок | Ввод символов |
| genkit/ai/генерировать/вывод/символы | Прилавок | Выходные символы |
| genkit/ai/генерировать/ввод/изображения | Прилавок | Ввод изображений |
| genkit/ai/генерировать/вывод/изображения | Прилавок | Вывод изображений |
| genkit/ai/генерировать/ввод/аудио | Прилавок | Входные аудиофайлы |
| genkit/ai/генерировать/вывод/аудио | Прилавок | Вывод аудиофайлов |
Каждая генерируемая метрика содержит следующие измерения:
| Имя | Описание |
|---|---|
| имя модели | Название модели |
| имя_функции | Имя выполняемого родительского объекта |
| путь | Путь выполнения от корня функции до этого действия. например. '/myFeature/parentAction/thisAction' |
| задержка мс | Время отклика модели |
| статус | «успех» или «неудача» в зависимости от того, был ли успешен запрос функции. |
| ошибка | Устанавливается только тогда, когда status=failure . Содержит тип ошибки, вызвавшей сбой. |
| источник | Исходный язык Genkit. Например. 'тс' |
| исходная версия | Версия платформы Genkit |
Визуализацию метрик можно выполнить с помощью обозревателя метрик. В меню слева нажмите «Обозреватель показателей» под заголовком «Обзор».
Выберите метрику, щелкнув раскрывающийся список «Выбрать метрику», выбрав «Общий узел», «Genkit» и метрику.
Визуализация метрики будет зависеть от ее типа (счетчик, гистограмма и т. д.). Обозреватель метрик предоставляет надежные средства агрегирования и запроса, помогающие отображать метрики в виде графиков по различным измерениям.
Задержка телеметрии
Перед отображением телеметрии для конкретного выполнения потока в операционном пакете Cloud может пройти небольшая задержка. В большинстве случаев эта задержка составляет менее 1 минуты.
Квоты и лимиты
Есть несколько квот, которые важно учитывать:
Расходы
Cloud Logging, Cloud Trace и Cloud Monitoring имеют щедрые бесплатные уровни. Конкретные цены можно найти по следующим ссылкам: