Events¶

Polycrate erzeugt für jede ausgeführte Action eine Transaction und ein Event. Das Logging von Workspace Transactions ist standardmäßig deaktiviert.

Event-System Architektur¶

sequenceDiagram
    participant User
    participant CLI as Polycrate CLI
    participant Container
    participant Handler as Event Handler
    participant Webhook
    participant LogFile as Log Directory

    User->>CLI: polycrate run myblock install
    CLI->>CLI: Generiere Transaction-ID
    CLI->>CLI: Erstelle Snapshot
    CLI->>Container: Führe Action aus

    alt Action erfolgreich
        Container-->>CLI: Exit 0
        CLI->>Handler: Event: success
    else Action fehlgeschlagen
        Container-->>CLI: Exit 1
        CLI->>Handler: Event: failure
    end

    alt workspace Handler konfiguriert
        Handler->>LogFile: Schreibe Event-YAML
        LogFile-->>Handler: Saved
    end

    alt webhook Handler konfiguriert
        Handler->>Webhook: POST Event-Payload
        Webhook-->>Handler: 200 OK
    end

    CLI-->>User: Output + Exit Code

    style CLI fill:#e1f5ff
    style Handler fill:#fff4e1
    style Webhook fill:#e1ffe1
    style LogFile fill:#ffe1e1

Event Handler¶

Event-Handler können in der Workspace-Konfiguration eingerichtet werden, um Events zu verarbeiten:

1. Workspace Handler¶

Der workspace Handler persistiert Events als YAML-Dateien im .logs/ Verzeichnis:

# workspace.poly
name: polycrate-demo

events:
  handler: workspace  # Schreibt Events in .logs/

Events werden dann in .logs/YYYY-MM-DD/<transaction-uuid>.yml gespeichert.

2. Webhook Handler¶

Der webhook Handler sendet Events an einen konfigurierten HTTP-Endpoint:

# workspace.poly
name: polycrate-demo

events:
  handler: webhook
  endpoint: https://example.com/api/events
  # Optional: Headers für Authentifizierung
  headers:
    Authorization: "Bearer YOUR_TOKEN"
    X-Custom-Header: "value"

Webhook-Payloads können für Integration mit Tools wie Slack, Discord, Datadog, etc. verwendet werden.

Event-Format¶

Ein von Polycrate erzeugtes Event sieht folgendermaßen aus:

labels:
  monk.event.class: polycrate
  monk.event.level: Info

workspace: my-workspace

block: my-block

action: install

command: 'polycrate run my-block install'
user_email: user@example.com

user_name: User Name

date: "2023-04-13T19:09:52+02:00"
transaction: 3159301c-0b5d-495d-8a31-e2e831723bbc

version: 0.18.21

config:
  handler: workspace

Event-Felder:

• labels.monk.event.class: Event-Kategorie (immer "polycrate")
• labels.monk.event.level: Event-Level (Info, Warning, Error)
• workspace: Name des Workspaces
• block: Name des ausgeführten Blocks
• action: Name der ausgeführten Action
• command: Vollständiger CLI-Befehl
• user_email / user_name: Informationen zum ausführenden User
• date: ISO 8601 Timestamp
• transaction: Eindeutige Transaction-ID
• version: Polycrate Version

Praktische Beispiele¶

Beispiel 1: Slack Integration¶

# workspace.poly
name: production-workspace

events:
  handler: webhook
  endpoint: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

workflows:
  - name: deploy-production
    steps:
      - name: deploy-app
        block: production-app
        action: deploy

Erstellen Sie einen Slack Webhook und alle Events werden automatisch an Ihren Slack-Channel gesendet.

Beispiel 2: Custom Event Processing¶

# workspace.poly
name: monitored-workspace

events:
  handler: webhook
  endpoint: https://api.mycompany.com/polycrate-events
  headers:
    Authorization: "Bearer ${POLYCRATE_EVENT_TOKEN}"

API-Endpoint-Beispiel (Node.js):

// Express.js endpoint
app.post('/polycrate-events', (req, res) => {
  const event = req.body;

  // Log event
  console.log(`Polycrate Event: ${event.block}:${event.action} - ${event.transaction}`);

  // Send to monitoring system
  if (event.labels['monk.event.level'] === 'Error') {
    sendToDatadog({
      title: `Polycrate Failure: ${event.block}`,
      text: `Action ${event.action} failed in workspace ${event.workspace}`,
      tags: [`workspace:${event.workspace}`, `block:${event.block}`],
      alert_type: 'error'
    });
  }

  // Store in database
  db.events.insert({
    transaction_id: event.transaction,
    workspace: event.workspace,
    block: event.block,
    action: event.action,
    timestamp: new Date(event.date),
    success: event.labels['monk.event.level'] === 'Info'
  });

  res.sendStatus(200);
});

Beispiel 3: Multi-Workspace Monitoring¶

# workspace-a.poly
name: workspace-a
events:
  handler: webhook
  endpoint: https://central-monitor.company.com/events
  headers:
    X-Workspace-ID: "workspace-a"

# workspace-b.poly
name: workspace-b
events:
  handler: webhook
  endpoint: https://central-monitor.company.com/events
  headers:
    X-Workspace-ID: "workspace-b"

Sammeln Sie Events von mehreren Workspaces in einem zentralen Monitoring-System.

Beispiel 4: CI/CD Integration¶

# .github/workflows/deploy.yml
name: Deploy with Polycrate

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Configure Polycrate Events
        run: |
          cat >> workspace.poly <<EOF
          events:
            handler: webhook
            endpoint: ${{ secrets.SLACK_WEBHOOK }}
          EOF

      - name: Deploy
        run: polycrate workflows run deploy-production

Beispiel 5: Debugging mit Workspace Handler¶

# workspace.poly (für Entwicklung/Debug)
name: dev-workspace

events:
  handler: workspace  # Lokales Logging für Debugging

# Events lokal inspizieren
ls -la .logs/$(date +%Y-%m-%d)/

# Neuestes Event anzeigen
ls -t .logs/*/*.yml | head -1 | xargs cat

# Events filtern
grep -r "monk.event.level: Error" .logs/

Event-Level¶

Events haben verschiedene Level basierend auf dem Action-Ergebnis:

graph LR
    Action[Action Execution] --> ExitCode{Exit Code?}

    ExitCode -->|0| Success[Event Level: Info]
    ExitCode -->|≠0| Failure[Event Level: Error]

    Success --> Handler[Event Handler]
    Failure --> Handler

    style Success fill:#e1ffe1
    style Failure fill:#ffe1e1
    style Handler fill:#fff4e1

• Info: Action wurde erfolgreich ausgeführt (Exit Code 0)
• Error: Action ist fehlgeschlagen (Exit Code ≠ 0)
• Warning: (Reserviert für zukünftige Features)

Best Practices¶

1. Webhook Authentifizierung¶

Sichern Sie Ihre Webhook-Endpoints mit Authentifizierung:

events:
  handler: webhook
  endpoint: https://api.company.com/events
  headers:
    Authorization: "Bearer ${WEBHOOK_TOKEN}"  # Aus Environment Variable

2. Fehler-Alerting¶

Richten Sie Alerting für fehlgeschlagene Events ein:

// Webhook Handler
if (event.labels['monk.event.level'] === 'Error') {
  sendAlert({
    channel: '#ops-critical',
    message: `🚨 Polycrate Deployment Failed!
    Workspace: ${event.workspace}
    Block: ${event.block}
    Action: ${event.action}
    Transaction: ${event.transaction}
    User: ${event.user_name}
    `
  });
}

3. Event-Retention¶

Begrenzen Sie die Speicherung von Events:

# Cron-Job: Alte Events löschen (älter als 30 Tage)
0 2 * * * find /path/to/workspace/.logs -type f -mtime +30 -delete

4. Strukturiertes Logging¶

Senden Sie Events an strukturierte Logging-Systeme:

events:
  handler: webhook
  endpoint: https://logs.datadoghq.com/api/v2/logs
  headers:
    DD-API-KEY: "${DATADOG_API_KEY}"

5. Event-Correlation¶

Nutzen Sie Transaction-IDs für Event-Correlation:

# Alle Events einer Transaction finden
TX_ID="550e8400-e29b-41d4-a716-446655440000"
grep -r "transaction: ${TX_ID}" .logs/

Troubleshooting¶

Webhook wird nicht aufgerufen¶

# Prüfen Event-Konfiguration
cat workspace.poly | grep -A 5 "events:"

# Prüfen Netzwerk-Verbindung
curl -X POST https://your-webhook.com/endpoint

# Prüfen Polycrate Logs
polycrate run myblock install --verbose

Events werden nicht geschrieben¶

# Prüfen ob .logs/ Verzeichnis existiert
ls -la .logs/

# Prüfen Berechtigungen
ls -la | grep .logs

# Manuell erstellen falls nötig
mkdir -p .logs

Webhook Timeout¶

# Erhöhen Sie Webhook-Timeout (falls unterstützt)
events:
  handler: webhook
  endpoint: https://slow-endpoint.com/events
  timeout: 30s  # Abhängig von Implementation

Zusammenhang mit anderen Konzepten¶

• Transactions: Jedes Event ist mit einer Transaction verknüpft
• Workflows: Workflow-Ausführung erzeugt Events für jeden Step
• Monitoring: Events können an Monitoring-Systeme wie Datadog, Prometheus oder Grafana gesendet werden