npm - @intentsolutionsio/vercel-pack - Versions diffs - 1.0.0 → 1.0.3 - Mend

@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (124) hide show

package/skills/vercel-observability/SKILL.md CHANGED Viewed

@@ -1,250 +1,260 @@
 ---
 name: vercel-observability
-description: |
-  Set up comprehensive observability for Vercel integrations with metrics, traces, and alerts.
-  Use when implementing monitoring for Vercel operations, setting up dashboards,
-  or configuring alerting for Vercel integration health.
+description: 'Set up Vercel observability with runtime logs, analytics, log drains,
+  and OpenTelemetry tracing.
+  Use when implementing monitoring for Vercel deployments, setting up log drains,
+  or configuring alerting for function errors and performance.
   Trigger with phrases like "vercel monitoring", "vercel metrics",
-  "vercel observability", "monitor vercel", "vercel alerts", "vercel tracing".
-allowed-tools: Read, Write, Edit
+  "vercel observability", "vercel logs", "vercel alerts", "vercel tracing".
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(curl:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- monitoring
+- observability
+- logging
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Vercel Observability
 ## Overview
-Set up comprehensive observability for Vercel integrations.
+Configure comprehensive observability for Vercel deployments using built-in analytics, runtime logs, log drains to external providers, OpenTelemetry integration, and custom instrumentation. Covers the full observability stack from function-level metrics to end-user experience monitoring.
 ## Prerequisites
-- Prometheus or compatible metrics backend
-- OpenTelemetry SDK installed
-- Grafana or similar dashboarding tool
-- AlertManager configured
-## Metrics Collection
+- Vercel Pro or Enterprise plan (for log drains and extended retention)
+- External logging provider (Datadog, Axiom, Sentry) — optional
+- OpenTelemetry SDK — optional
-### Key Metrics
-| Metric | Type | Description |
-|--------|------|-------------|
-| `vercel_requests_total` | Counter | Total API requests |
-| `vercel_request_duration_seconds` | Histogram | Request latency |
-| `vercel_errors_total` | Counter | Error count by type |
-| `vercel_rate_limit_remaining` | Gauge | Rate limit headroom |
+## Instructions
+### Step 1: Enable Vercel Analytics
+In the Vercel dashboard:
-### Prometheus Metrics
+1. Go to **Analytics** tab
+2. Enable **Web Analytics** (Core Web Vitals, page views)
+3. Enable **Speed Insights** (real user performance data)
 ```typescript
-import { Registry, Counter, Histogram, Gauge } from 'prom-client';
+// For Next.js — add the analytics component
+// src/app/layout.tsx
+import { Analytics } from '@vercel/analytics/react';
+import { SpeedInsights } from '@vercel/speed-insights/next';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+        <SpeedInsights />
+      </body>
+    </html>
+  );
+}
+```
-const registry = new Registry();
+Install: `npm install @vercel/analytics @vercel/speed-insights`
-const requestCounter = new Counter({
-  name: 'vercel_requests_total',
-  help: 'Total Vercel API requests',
-  labelNames: ['method', 'status'],
-  registers: [registry],
-});
+### Step 2: Runtime Logs
-const requestDuration = new Histogram({
-  name: 'vercel_request_duration_seconds',
-  help: 'Vercel request duration',
-  labelNames: ['method'],
-  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
-  registers: [registry],
-});
+```bash
+# View runtime logs via CLI
+vercel logs https://my-app.vercel.app --follow
-const errorCounter = new Counter({
-  name: 'vercel_errors_total',
-  help: 'Vercel errors by type',
-  labelNames: ['error_type'],
-  registers: [registry],
-});
+# Filter by level
+vercel logs https://my-app.vercel.app --level=error
+# View logs via API
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v2/deployments/dpl_xxx/events?limit=50&direction=backward" \
+  | jq '.[] | {timestamp: .created, level: .level, message: .text}'
 ```
-### Instrumented Client
+Runtime logs include:
+- Function invocation start/end with duration
+- `console.log/warn/error` output from functions
+- Edge Middleware execution logs
+- HTTP request/response metadata
+### Step 3: Structured Logging in Functions
 ```typescript
-async function instrumentedRequest<T>(
-  method: string,
-  operation: () => Promise<T>
-): Promise<T> {
-  const timer = requestDuration.startTimer({ method });
+// lib/logger.ts — structured JSON logging
+interface LogEntry {
+  level: 'info' | 'warn' | 'error';
+  message: string;
+  requestId?: string;
+  duration?: number;
+  [key: string]: unknown;
+}
-  try {
-    const result = await operation();
-    requestCounter.inc({ method, status: 'success' });
-    return result;
-  } catch (error: any) {
-    requestCounter.inc({ method, status: 'error' });
-    errorCounter.inc({ error_type: error.code || 'unknown' });
-    throw error;
-  } finally {
-    timer();
+export function log(entry: LogEntry): void {
+  // Vercel captures console output as runtime logs
+  const output = JSON.stringify({
+    ...entry,
+    timestamp: new Date().toISOString(),
+    region: process.env.VERCEL_REGION,
+    env: process.env.VERCEL_ENV,
+  });
+  switch (entry.level) {
+    case 'error': console.error(output); break;
+    case 'warn': console.warn(output); break;
+    default: console.log(output);
   }
 }
-```
-## Distributed Tracing
-### OpenTelemetry Setup
+// Usage in API route:
+export async function GET(request: Request) {
+  const requestId = crypto.randomUUID();
+  const start = Date.now();
-```typescript
-import { trace, SpanStatusCode } from '@opentelemetry/api';
-const tracer = trace.getTracer('vercel-client');
-async function tracedVercelCall<T>(
-  operationName: string,
-  operation: () => Promise<T>
-): Promise<T> {
-  return tracer.startActiveSpan(`vercel.${operationName}`, async (span) => {
-    try {
-      const result = await operation();
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error: any) {
-      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
-      span.recordException(error);
-      throw error;
-    } finally {
-      span.end();
-    }
-  });
+  try {
+    const data = await fetchData();
+    log({ level: 'info', message: 'Fetched data', requestId, duration: Date.now() - start });
+    return Response.json(data);
+  } catch (error) {
+    log({ level: 'error', message: 'Data fetch failed', requestId, error: String(error) });
+    return Response.json({ error: 'Internal error', requestId }, { status: 500 });
+  }
 }
 ```
-## Logging Strategy
+### Step 4: Log Drains (External Providers)
+Configure log drains to send all Vercel logs to your logging provider:
+In dashboard: **Settings > Log Drains > Add**
+Supported providers:
+| Provider | Type | Setup |
+|----------|------|-------|
+| Datadog | HTTP | API key + site URL |
+| Axiom | HTTP | API token + dataset |
+| Sentry | HTTP | DSN |
+| Custom | HTTP/NDJSON | Any HTTPS endpoint |
+| Grafana Loki | HTTP | Push URL + auth |
+Log drain delivers:
+- **Runtime logs**: function invocations, console output
+- **Build logs**: build step output, warnings, errors
+- **Static logs**: CDN access logs (edge)
+- **Firewall logs**: WAF events
+```bash
+# Create a log drain via API
+curl -X POST "https://api.vercel.com/v2/integrations/log-drains" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-datadog-drain",
+    "type": "json",
+    "url": "https://http-intake.logs.datadoghq.com/api/v2/logs",
+    "headers": {"DD-API-KEY": "your-datadog-api-key"},
+    "sources": ["lambda", "edge", "build", "static"]
+  }'
+```
-### Structured Logging
+### Step 5: OpenTelemetry Integration
 ```typescript
-import pino from 'pino';
-const logger = pino({
-  name: 'vercel',
-  level: process.env.LOG_LEVEL || 'info',
-});
-function logVercelOperation(
-  operation: string,
-  data: Record<string, any>,
-  duration: number
-) {
-  logger.info({
-    service: 'vercel',
-    operation,
-    duration_ms: duration,
-    ...data,
+// instrumentation.ts (Next.js 13.4+)
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+export function register() {
+  const sdk = new NodeSDK({
+    traceExporter: new OTLPTraceExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+    }),
+    instrumentations: [getNodeAutoInstrumentations()],
+    serviceName: 'my-vercel-app',
   });
+  sdk.start();
 }
 ```
-## Alert Configuration
-### Prometheus AlertManager Rules
-```yaml
-# vercel_alerts.yaml
-groups:
-  - name: vercel_alerts
-    rules:
-      - alert: VercelHighErrorRate
-        expr: |
-          rate(vercel_errors_total[5m]) /
-          rate(vercel_requests_total[5m]) > 0.05
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Vercel error rate > 5%"
-      - alert: VercelHighLatency
-        expr: |
-          histogram_quantile(0.95,
-            rate(vercel_request_duration_seconds_bucket[5m])
-          ) > 2
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Vercel P95 latency > 2s"
-      - alert: VercelDown
-        expr: up{job="vercel"} == 0
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Vercel integration is down"
-```
-## Dashboard
-### Grafana Panel Queries
-```json
-{
-  "panels": [
-    {
-      "title": "Vercel Request Rate",
-      "targets": [{
-        "expr": "rate(vercel_requests_total[5m])"
-      }]
-    },
-    {
-      "title": "Vercel Latency P50/P95/P99",
-      "targets": [{
-        "expr": "histogram_quantile(0.5, rate(vercel_request_duration_seconds_bucket[5m]))"
-      }]
-    }
-  ]
-}
+```javascript
+// next.config.js
+module.exports = {
+  experimental: {
+    instrumentationHook: true,
+  },
+};
 ```
-## Instructions
+### Step 6: Error Tracking with Sentry
-### Step 1: Set Up Metrics Collection
-Implement Prometheus counters, histograms, and gauges for key operations.
+```bash
+npx @sentry/wizard@latest -i nextjs
+```
-### Step 2: Add Distributed Tracing
-Integrate OpenTelemetry for end-to-end request tracing.
+```typescript
+// sentry.client.config.ts
+import * as Sentry from '@sentry/nextjs';
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  environment: process.env.VERCEL_ENV,
+  release: process.env.VERCEL_GIT_COMMIT_SHA,
+  tracesSampleRate: process.env.VERCEL_ENV === 'production' ? 0.1 : 1.0,
+});
+```
-### Step 3: Configure Structured Logging
-Set up JSON logging with consistent field names.
+## Monitoring Dashboard Checklist
-### Step 4: Create Alert Rules
-Define Prometheus alerting rules for error rates and latency.
+| Metric | Source | Alert Threshold |
+|--------|--------|----------------|
+| Error rate | Runtime logs | > 1% of requests |
+| P95 function latency | Vercel Analytics | > 2s |
+| Cold start frequency | Runtime logs | > 20% of invocations |
+| Build success rate | Build logs | Any failure |
+| Core Web Vitals (LCP) | Speed Insights | > 2.5s |
+| Edge cache hit rate | Static logs | < 80% |
 ## Output
-- Metrics collection enabled
-- Distributed tracing configured
-- Structured logging implemented
-- Alert rules deployed
-## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Missing metrics | No instrumentation | Wrap client calls |
-| Trace gaps | Missing propagation | Check context headers |
-| Alert storms | Wrong thresholds | Tune alert rules |
-| High cardinality | Too many labels | Reduce label values |
+- Vercel Analytics and Speed Insights enabled
+- Structured JSON logging in all functions
+- Log drains configured to external provider
+- Error tracking with Sentry or equivalent
+- OpenTelemetry tracing for distributed systems
-## Examples
+## Error Handling
-### Quick Metrics Endpoint
-```typescript
-app.get('/metrics', async (req, res) => {
-  res.set('Content-Type', registry.contentType);
-  res.send(await registry.metrics());
-});
-```
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Logs missing | Log retention expired (1hr free, 30d with Plus) | Enable log drains for persistence |
+| Analytics not tracking | Missing `<Analytics />` component | Add to root layout |
+| Log drain not receiving | Wrong URL or auth headers | Test the endpoint directly with curl |
+| Sentry not capturing errors | DSN not set in production env | Add `NEXT_PUBLIC_SENTRY_DSN` to Production scope |
+| OTEL traces missing | instrumentation.ts not loaded | Enable `instrumentationHook` in next.config.js |
 ## Resources
-- [Prometheus Best Practices](https://prometheus.io/docs/practices/naming/)
-- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
-- [Vercel Observability Guide](https://vercel.com/docs/observability)
+- [Vercel Observability](https://vercel.com/docs/observability)
+- [Runtime Logs](https://vercel.com/docs/logs/runtime)
+- [Vercel Analytics](https://vercel.com/docs/analytics)
+- [Speed Insights](https://vercel.com/docs/speed-insights)
+- [Log Drains](https://vercel.com/docs/observability/log-drains)
+- [OpenTelemetry + Next.js](https://nextjs.org/docs/app/building-your-application/optimizing/open-telemetry)
 ## Next Steps
-For incident response, see `vercel-incident-runbook`.
+For incident response, see `vercel-incident-runbook`.

package/skills/vercel-observability/references/alert-configuration.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Alert Configuration
+## Alert Configuration
+### Prometheus AlertManager Rules
+```yaml
+# vercel_alerts.yaml
+groups:
+  - name: vercel_alerts
+    rules:
+      - alert: VercelHighErrorRate
+        expr: |
+          rate(vercel_errors_total[5m]) /
+          rate(vercel_requests_total[5m]) > 0.05
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Vercel error rate > 5%"
+      - alert: VercelHighLatency
+        expr: |
+          histogram_quantile(0.95,
+            rate(vercel_request_duration_seconds_bucket[5m])
+          ) > 2
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Vercel P95 latency > 2s"
+      - alert: VercelDown
+        expr: up{job="vercel"} == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Vercel integration is down"
+```

package/skills/vercel-observability/references/errors.md ADDED Viewed

@@ -0,0 +1,11 @@
+# Error Handling Reference
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Missing metrics | No instrumentation | Wrap client calls |
+| Trace gaps | Missing propagation | Check context headers |
+| Alert storms | Wrong thresholds | Tune alert rules |
+| High cardinality | Too many labels | Reduce label values |
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-observability/references/examples.md ADDED Viewed

@@ -0,0 +1,13 @@
+## Examples
+### Quick Metrics Endpoint
+```typescript
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', registry.contentType);
+  res.send(await registry.metrics());
+});
+```
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-observability/references/metrics-collection.md ADDED Viewed

@@ -0,0 +1,65 @@
+# Metrics Collection
+## Metrics Collection
+### Key Metrics
+| Metric | Type | Description |
+|--------|------|-------------|
+| `vercel_requests_total` | Counter | Total API requests |
+| `vercel_request_duration_seconds` | Histogram | Request latency |
+| `vercel_errors_total` | Counter | Error count by type |
+| `vercel_rate_limit_remaining` | Gauge | Rate limit headroom |
+### Prometheus Metrics
+```typescript
+import { Registry, Counter, Histogram, Gauge } from 'prom-client';
+const registry = new Registry();
+const requestCounter = new Counter({
+  name: 'vercel_requests_total',
+  help: 'Total Vercel API requests',
+  labelNames: ['method', 'status'],
+  registers: [registry],
+});
+const requestDuration = new Histogram({
+  name: 'vercel_request_duration_seconds',
+  help: 'Vercel request duration',
+  labelNames: ['method'],
+  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+  registers: [registry],
+});
+const errorCounter = new Counter({
+  name: 'vercel_errors_total',
+  help: 'Vercel errors by type',
+  labelNames: ['error_type'],
+  registers: [registry],
+});
+```
+### Instrumented Client
+```typescript
+async function instrumentedRequest<T>(
+  method: string,
+  operation: () => Promise<T>
+): Promise<T> {
+  const timer = requestDuration.startTimer({ method });
+  try {
+    const result = await operation();
+    requestCounter.inc({ method, status: 'success' });
+    return result;
+  } catch (error: any) {
+    requestCounter.inc({ method, status: 'error' });
+    errorCounter.inc({ error_type: error.code || 'unknown' });
+    throw error;
+  } finally {
+    timer();
+  }
+}
+```