К основному содержанию
скилл CX Codex

lokalise-observability — скилл Claude Code: обзор и установка

Скилл lokalise-observability настраивает сбор метрик для интеграций с Lokalise: время ответов API, готовность переводов и вызовы вебхуков. Пригодится при отладке пайплайнов локализации.

MIT 1 установок ★ 2 935 обновлён 2026-11-01

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-observability -a claude-code
Открыть на GitHub

Что делает lokalise-observability

Скилл внедряет мониторинг для пайплайна переводов Lokalise. Он оборачивает вызовы SDK @lokalise/node-api, собирая длительность ответов, ошибки и расход лимитов по заголовкам x-ratelimit-remaining. Для контроля готовности текстов код опрашивает статистику проекта с интервалом в 5 минут и передаёт число оставшихся слов в виде gauge-метрик по каждой локали.

Внутри есть готовый обработчик входящих вебхуков на Express. Сервис Lokalise прерывает доставку по таймауту через 8 секунд, поэтому приём вебхука подтверждается сразу статусом 200, а метрики времени обработки пишутся отдельно. Без установленной библиотеки @lokalise/node-api и токена с правами чтения эти сценарии запустить не получится.

Какие задачи решает

  • замерять задержки и ошибки при вызовах к API Lokalise
  • снимать метрики готовности переводов по отдельным языкам
  • контролировать остаток лимита запросов по HTTP-заголовкам
  • логировать сбои и время обработки входящих вебхуков

Примеры запросов агенту

  • Настрой мониторинг вызовов API и метрики ошибок для Lokalise
  • Сделай проверку остатка rate limit для API Lokalise
  • Добавь сбор метрик готовности переводов по локалям

Как установить lokalise-observability

1Через Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-observability -a claude-code

2Вручную: положить файлы

~/.claude/skills/lokalise-observability/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/lokalise-observability/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о lokalise-observability

Как установить lokalise-observability в Claude Code?

Выполните команду npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-observability -a claude-code. Файл скилла сохранится по пути ~/.claude/skills/lokalise-observability/SKILL.md.

Что делает скилл lokalise-observability?

Он предоставляет готовые шаблоны для сбора метрик из @lokalise/node-api, экспорта данных в Prometheus или Datadog и контроля вебхуков.

Почему обработчик вебхука отвечает сразу?

Lokalise отключает соединение через 8 секунд. Моментальный ответ со статусом 200 исключает ошибки таймаута со стороны сервиса.

Исходный текст

SKILL.md · MIT
---
name: lokalise-observability
description: 'Set up comprehensive observability for Lokalise integrations with metrics,
  traces, and alerts.

  Use when implementing monitoring for Lokalise operations, setting up dashboards,

  or configuring alerting for Lokalise integration health.

  Trigger with phrases like "lokalise monitoring", "lokalise metrics",

  "lokalise observability", "monitor lokalise", "lokalise alerts", "lokalise tracing".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(jq:*), Bash(npm:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lokalise
- monitoring
- observability
- dashboard
compatibility: Designed for Claude Code
---
# Lokalise Observability

## Overview

Monitor Lokalise translation pipeline health: API response times, rate limit consumption, translation completion rates, webhook delivery reliability, file upload/download status, and per-word cost tracking. Built around the `@lokalise/node-api` SDK with Prometheus-compatible metrics and alerting rules.

## Prerequisites

- `@lokalise/node-api` SDK installed
- Metrics backend (Prometheus, Datadog, CloudWatch, or OpenTelemetry collector)
- Lokalise API token with read access
- Optional: webhook endpoint for real-time event monitoring

## Instructions

### Step 1: Instrument API Calls with Metrics

Wrap every SDK call to emit duration, success/failure counts, and rate limit status.

```typescript
import { LokaliseApi } from "@lokalise/node-api";

interface MetricLabels {
  operation: string;
  status: "ok" | "error";
  code?: string;
}

// Implement this to emit to your metrics backend
declare function emitHistogram(name: string, value: number, labels: MetricLabels): void;
declare function emitCounter(name: string, value: number, labels: MetricLabels): void;

const lok = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });

async function trackedApiCall<T>(
  operation: string,
  fn: () => Promise<T>
): Promise<T> {
  const start = performance.now();
  try {
    const result = await fn();
    const durationMs = performance.now() - start;

    emitHistogram("lokalise_api_duration_ms", durationMs, {
      operation,
      status: "ok",
    });
    emitCounter("lokalise_api_requests_total", 1, {
      operation,
      status: "ok",
    });

    return result;
  } catch (err: unknown) {
    const code = (err as { code?: number })?.code?.toString() ?? "unknown";
    const durationMs = performance.now() - start;

    emitHistogram("lokalise_api_duration_ms", durationMs, {
      operation,
      status: "error",
      code,
    });
    emitCounter("lokalise_api_requests_total", 1, {
      operation,
      status: "error",
      code,
    });

    throw err;
  }
}

// Usage — wrap every SDK call
const keys = await trackedApiCall("keys.list", () =>
  lok.keys().list({ project_id: projectId, limit: 500 })
);

const bundle = await trackedApiCall("files.download", () =>
  lok.files().download(projectId, {
    format: "json",
    filter_langs: ["en"],
    original_filenames: false,
  })
);
```

### Step 2: Monitor Translation Completion

Poll project statistics and emit per-locale progress as gauge metrics.

```typescript
declare function emitGauge(name: string, value: number, labels: Record<string, string>): void;

async function collectTranslationMetrics(projectId: string): Promise<void> {
  const project = await trackedApiCall("projects.get", () =>
    lok.projects().get(projectId)
  );

  // Overall progress
  emitGauge("lokalise_translation_progress_pct", project.statistics?.progress_total ?? 0, {
    project: projectId,
    locale: "all",
  });

  emitGauge("lokalise_keys_total", project.statistics?.keys_total ?? 0, {
    project: projectId,
  });

  // Per-language progress
  const languages = await trackedApiCall("languages.list", () =>
    lok.languages().list({ project_id: projectId, limit: 100 })
  );

  for (const lang of languages.items) {
    emitGauge("lokalise_translation_progress_pct", lang.statistics?.progress ?? 0, {
      project: projectId,
      locale: lang.lang_iso,
    });
    emitGauge("lokalise_words_to_do", lang.statistics?.words_to_do ?? 0, {
      project: projectId,
      locale: lang.lang_iso,
    });
  }
}

// Run on a schedule (every 5 minutes)
// setInterval(() => collectTranslationMetrics(projectId), 5 * 60_000);
```

### Step 3: Track Rate Limit Consumption

```bash
set -euo pipefail
# Quick rate limit check — call from a monitoring cron job
HEADERS=$(curl -sI "https://api.lokalise.com/api2/projects?limit=1" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" 2>/dev/null)

LIMIT=$(echo "$HEADERS" | grep -i "x-ratelimit-limit" | awk '{print $2}' | tr -d '\r')
REMAINING=$(echo "$HEADERS" | grep -i "x-ratelimit-remaining" | awk '{print $2}' | tr -d '\r')
RESET=$(echo "$HEADERS" | grep -i "x-ratelimit-reset" | awk '{print $2}' | tr -d '\r')

echo "Rate limit: ${REMAINING}/${LIMIT} remaining (resets at ${RESET})"

# Emit as metrics for Prometheus/Datadog
# lokalise_rate_limit_remaining ${REMAINING}
# lokalise_rate_limit_max ${LIMIT}
```

### Step 4: Monitor Webhook Delivery

Track webhook processing success and latency in your webhook handler.

```typescript
import express from "express";

const webhookMetrics = {
  received: 0,
  processed: 0,
  failed: 0,
  totalLatencyMs: 0,
};

app.post("/webhooks/lokalise", async (req: express.Request, res: express.Response) => {
  webhookMetrics.received++;
  const start = performance.now();

  // Respond immediately — Lokalise times out after 8 seconds
  res.status(200).json({ received: true });

  try {
    await processWebhookEvent(req.body);
    webhookMetrics.processed++;
  } catch (error) {
    webhookMetrics.failed++;
    console.error("Webhook processing failed:", error);
  }

  const latencyMs = performance.now() - start;
  webhookMetrics.totalLatencyMs += latencyMs;

  emitCounter("lokalise_webhook_received_total", 1, {
    event: req.body.event,
    status: webhookMetrics.failed > 0 ? "error" : "ok",
  });
  emitHistogram("lokalise_webhook_processing_ms", latencyMs, {
    event: req.body.event,
    status: "ok",
  });
});

// Health endpoint exposing webhook metrics
app.get("/metrics/webhooks", (_req, res) => {
  res.json({
    received: webhookMetrics.received,
    processed: webhookMetrics.processed,
    failed: webhookMetrics.failed,
    avgLatencyMs: webhookMetrics.received > 0
      ? Math.round(webhookMetrics.totalLatencyMs / webhookMetrics.received)
      : 0,
  });
});
```

### Step 5: Register Webhooks for Key Events

```bash
set -euo pipefail
# Subscribe to events that matter for pipeline monitoring
curl -s -X POST "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}/webhooks" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.company.com/lokalise",
    "events": [
      "project.imported",
      "project.exported",
      "project.key.added",
      "project.key.modified",
      "project.translation.updated",
      "project.translation.proofread",
      "project.task.closed",
      "project.contributor.added"
    ]
  }' | jq '{webhook_id: .webhook.webhook_id, events: .webhook.events}'
```

### Step 6: Prometheus Alerting Rules

```yaml
groups:
  - name: lokalise
    rules:
      - alert: LokaliseApiRateLimited
        expr: rate(lokalise_api_requests_total{status="error", code="429"}[5m]) > 0
        for: 2m
        annotations:
          summary: "Lokalise API rate limit hit — requests being throttled"
          runbook: "Check for runaway loops. Lokalise limit is 6 req/sec per token."

      - alert: LokaliseApiErrors
        expr: rate(lokalise_api_requests_total{status="error", code=~"5.."}[10m]) > 0.1
        for: 5m
        annotations:
          summary: "Lokalise API returning 5xx errors"
          runbook: "Check https://status.lokalise.com. Enable fallback translations."

      - alert: TranslationProgressStalled
        expr: lokalise_translation_progress_pct < 80 and changes(lokalise_translation_progress_pct[24h]) == 0
        for: 24h
        annotations:
          summary: "Translation progress stalled at {{ $value }}% for 24+ hours"

      - alert: WebhookDeliveryFailing
        expr: rate(lokalise_webhook_received_total{status="error"}[1h]) > 3
        annotations:
          summary: "Lokalise webhook deliveries failing ({{ $value }} errors/hour)"

      - alert: LokaliseApiLatencyHigh
        expr: histogram_quantile(0.95, rate(lokalise_api_duration_ms_bucket[5m])) > 5000
        for: 10m
        annotations:
          summary: "Lokalise API P95 latency above 5 seconds"
```

### Step 7: Translation Pipeline Dashboard Spec

Key panels for Grafana/Datadog:

| Panel | Metric | Type |
|-------|--------|------|
| API Request Rate | `rate(lokalise_api_requests_total[5m])` | Time series |
| API Latency P50/P95 | `histogram_quantile(0.5/0.95, ...)` | Time series |
| Rate Limit Remaining | `lokalise_rate_limit_remaining` | Gauge |
| Translation Progress | `lokalise_translation_progress_pct` by locale | Bar chart |
| Words Remaining | `lokalise_words_to_do` by locale | Bar chart |
| Webhook Success Rate | `rate(lokalise_webhook_received_total{status="ok"}[5m])` | Time series |
| Error Rate by Code | `rate(lokalise_api_requests_total{status="error"}[5m])` by code | Stacked area |

## Output

- `trackedApiCall()` wrapper emitting duration and error metrics for every Lokalise API operation
- Translation progress gauge metrics broken down by project and locale
- Rate limit consumption monitoring via response headers
- Webhook delivery tracking with latency and error counters
- Prometheus alerting rules for rate limiting, API errors, stalled progress, and webhook failures
- Dashboard specification with 7 panels covering the full translation pipeline

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| `429 Too Many Requests` | Exceeded 6 req/sec rate limit | Add request throttling with p-queue |
| Webhook not firing | Wrong event type registered | Verify event names match API reference |
| Progress metric stuck at 0 | Language not added to project | Add target locale in Lokalise project settings |
| Stale metrics | Polling interval too long | Reduce collection interval to 5 minutes |
| High cardinality | Too many label values | Limit `operation` labels to top-level SDK methods |

## Examples

### Verify a stalled translation pipeline before paging a team

An alert reports that French translations have remained at 74% for a day. First
query the project statistic and the webhook/error metrics for the same window;
do not assume that a low progress value is an API outage. If API latency and
error rate are normal but no `project.translation.updated` events arrived,
route the incident to the translation owner with the project and locale. If
the webhook error metric is elevated, preserve the failed delivery identifiers
and use the webhook runbook before replaying or changing any production data.

## Resources

- [Lokalise Webhooks API](https://developers.lokalise.com/reference/create-a-webhook)
- [Lokalise Webhook Events](https://developers.lokalise.com/docs/webhook-events)
- [Lokalise API Rate Limits](https://developers.lokalise.com/reference/api-rate-limits)
- [Lokalise Project Statistics](https://developers.lokalise.com/reference/retrieve-a-project)
- [Prometheus Alerting Rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
- [p-queue](https://github.com/sindresorhus/p-queue) — rate-limited request queue

## Next Steps

For setting up real-time automation based on webhook events, see `lokalise-webhooks-events`. For incident response procedures when alerts fire, see `lokalise-incident-runbook`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
redis-observability Redis, Inc. Скилл redis-observability подсказывает, какие метрики Redis держать под наблюдением и какие встроенные команды запускать при разборе инцидентов. CX Codex +1 2 600установок observability-sre majiayu000 Скилл observability-sre помогает настраивать наблюдаемость, SLO и процессы реагирования на инциденты. Подключайте его при работе с Prometheus, Grafana и OpenTelemetry. CX Codex +1 165установок observability-engineer davila7 Скилл observability-engineer для Claude Code проектирует мониторинг, логи и трассировку, задаёт SLI/SLO и помогает разбирать сбои продакшена. Разбирает шумные алерты при большом числе сервисов. CX Codex +1 93установок grafana-dashboard aj-geddes Скилл grafana-dashboard для Claude Code, Cursor и Codex генерирует JSON-конфигурации дашбордов Grafana с панелями, переменными и алертами. Включается, когда нужно собрать мониторинг приложения или визуализировать метрики из Prometheus. CX Codex +1 503установок setup-monitoring-observability davila7 Команда setup-monitoring-observability настраивает наблюдаемость проекта: метрики, логи, трассировку и оповещения. Укажите нужный тип или запросите полный стек. CX Codex +1 279установок application-performance-observability-engineer Seth Hobson Субагент application-performance-observability-engineer для мониторинга, логов и трейсинга: настраивает метрики, алерты и SLO в продакшене. CX Codex ★ 42 780звёзд репо

Из того же набора139

Весь набор →
gc-log-analyzer Скилл для разбора логов сборщика мусора в задачах нагрузочного тестирования. Автоматически включается при упоминании gc log analyzer в запросе. CX Codex +1 1установок klingai-audit-logging Скилл klingai-audit-logging настраивает защищённый журнал аудита для вызовов Kling AI API. Он фиксирует генерации видео, изменения статусов и хеширует промпты. CX Codex +1 1установок openrouter-audit-logging Скилл openrouter-audit-logging для Claude Code записывает метаданные вызовов OpenRouter, стоимость и хеш промпта. Данные помогают разбирать ошибки и учитывать использование моделей. CX Codex +1 1установок monitoring-whale-activity Скилл monitoring-whale-activity для Claude Code отслеживает крупные криптотранзакции и движения кошельков китов в реальном времени на нескольких блокчейнах. Запускается по запросам об активности китов и крупных переводах. CX Codex +1 1установок model-evaluation-metrics Скилл model-evaluation-metrics помогает разбирать метрики оценки моделей, создавать код и конфигурации для ML Training и проверять результаты. CX Codex +1 1установок date-range-analyzer Скилл для разбора временных диапазонов в задачах по аналитике данных. Включается сам, когда в запросе упоминается date range analyzer. CX Codex +1 1установок data-story-outliner Скилл data-story-outliner для платформ Claude Code, Codex, Cursor и других помощников ИИ, который автоматически включается при работе с аналитическими данными. CX Codex +1 1установок retention-calculator Скилл помогает разбирать задачи retention calculator в аналитике данных, готовит код и конфигурации. Активируется по запросу о retention. CX Codex +1 1установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой