Instalacja - REST API

Zanim zaczniesz, utwórz projekt w panelu DockRay. W jego ustawieniach znajdziesz token projektu - publiczny identyfikator, który wchodzi do adresu endpointu - a w zakładce Klucze API wygenerujesz klucz prywatny. Klucz jest pokazywany tylko raz, w momencie generowania: w bazie DockRay leży wyłącznie jego skrót. Jeżeli nie masz jeszcze projektu, zacznij od zakładania konta i pierwszego projektu.

Dwa endpointy

{token} w adresie to publiczny token projektu - ten sam, który widać w panelu przy każdej integracji. Wchodzi wprost do adresu, bo nie jest sekretem.

Uwierzytelnianie

Klucz prywatny można przekazać na trzy sposoby, sprawdzane w tej kolejności:

1. parametr api_token w adresie,
2. pole formularza api_token w ciele żądania,
3. nagłówek Authorization: Bearer.

Nagłówek jest wyborem najbezpieczniejszym: parametry adresu trafiają do logów serwerów pośredniczących, a pole formularza wymaga ciała typu application/x-www-form-urlencoded, którego zwykle nie używa się do wysyłki JSON-a.

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"
        }
      ]
    }
  }'

Ciało żądania

JSON, opcjonalnie spakowany gzipem z nagłówkiem Content-Encoding: gzip. Gdy ciało jest spakowane, klucz nie może iść polem formularza - parser czyta skompresowany strumień jako JSON wprost, więc pole wewnątrz niego nigdy nie zostanie odczytane. Przy gzipie klucz zawsze musi trafić do adresu albo do nagłówka.

Minimalne zgłoszenie błędu

Jedyne wymagane pola to typ i treść wyjątku:

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

Reszta pól jest opcjonalna, ale każde dokłada coś do diagnozy w panelu: stos wywołań (exception.values[0].stacktrace), nazwa i wersja klienta (sdk.name, sdk.version), środowisko, system operacyjny i runtime (contexts.os.*, contexts.runtime), kontekst żądania (request.url, request.method, request.headers) oraz dane użytkownika (user.id, user.username, user.email, user.ip_address, user.agent).

Minimalne zgłoszenie transakcji

Jedyne wymagane pole to niepuste contexts.trace.data:

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

Pierwszy 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":"Kontrolny komunikat DockRay"}]}}'

Odpowiedź 200 {"success": true} znaczy, że zdarzenie zostało przyjęte. Sprawdź panel w sekcji Błędy projektu wskazanego przez token.