Installation - REST API

Erstelle zuerst ein Projekt im DockRay-Panel. In seinen Einstellungen findest du den Projekt-Token - die öffentliche Kennung, die in die Ingest-URL eingeht - und im Tab API-Schlüssel erzeugst du einen privaten Schlüssel. Der Schlüssel wird nur einmal angezeigt, beim Erzeugen: DockRay speichert lediglich seinen Hash. Wenn noch kein Projekt existiert, beginne mit Erste Schritte.

Zwei Endpunkte

{token} in der Adresse ist der öffentliche Token des Projekts - derselbe, der im Panel bei jeder Integration angezeigt wird. Er steht direkt in der URL, weil er kein Geheimnis ist.

Authentifizierung

Der private Schlüssel kann auf drei Arten übergeben werden, geprüft in dieser Reihenfolge:

1. der Query-Parameter api_token,
2. das Formularfeld api_token im Request-Body,
3. der Header Authorization: Bearer.

Der Header ist die sicherste Wahl: Query-Parameter landen in Proxy- und Server-Logs, und ein Formularfeld braucht einen Body vom Typ application/x-www-form-urlencoded, was man normalerweise nicht zum Versenden von JSON nutzt.

curl -X POST https://dockray.io/api/v1/PROJECT_TOKEN/project \
  -H 'Authorization: Bearer PROJECT_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "exception": {
      "values": [
        {
          "type": "RuntimeException",
          "value": "Payment gateway returned an unexpected response"
        }
      ]
    }
  }'

Request-Body

JSON, optional gzip-komprimiert mit dem Header Content-Encoding: gzip. Ist der Body komprimiert, kann der Schlüssel nicht als Formularfeld mitreisen - der Parser liest den komprimierten Stream direkt als JSON, ein Feld darin wird also nie gelesen. Bei gzip muss der Schlüssel immer in die URL oder in den Header.

Die kleinstmögliche Fehlermeldung

Die einzigen Pflichtfelder sind Typ und Wert der Ausnahme:

{
    "exception": {
        "values": [
            {
                "type": "RuntimeException",
                "value": "Payment gateway returned an unexpected response"
            }
        ]
    }
}

Alles andere ist optional, trägt aber jeweils zur Diagnose im Panel bei: der Stacktrace (exception.values[0].stacktrace), Name und Version des Clients (sdk.name, sdk.version), Umgebung, Betriebssystem und Runtime (contexts.os.*, contexts.runtime), der Anfragekontext (request.url, request.method, request.headers) sowie Benutzerdaten (user.id, user.username, user.email, user.ip_address, user.agent).

Die kleinstmögliche Transaktionsmeldung

Das einzige Pflichtfeld ist ein nicht leeres contexts.trace.data:

{
    "transaction": "POST /api/orders",
    "contexts": {
        "trace": {
            "data": {
                "url": "https://api.example.com/api/orders",
                "method": "POST"
            }
        }
    },
    "tags": {
        "http.status_code": "200"
    }
}

Der erste Test

curl -X POST https://dockray.io/api/v1/PROJECT_TOKEN/project \
  -H 'Authorization: Bearer PROJECT_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"exception":{"values":[{"type":"RuntimeException","value":"DockRay-Kontrollmeldung"}]}}'

Eine Antwort 200 {"success": true} bedeutet, dass das Ereignis angenommen wurde. Prüfe das Panel unter Fehler des Projekts, auf das der Token zeigt.