Installation - REST API

Before you start, create a project in the DockRay panel. Its settings hold the project token - the public identifier that goes into the ingest URL - and the API keys tab is where you generate a private key. The key is shown once, when it is generated: DockRay stores only its hash. If you do not have a project yet, start with Getting Started.

Two endpoints

{token} in the address is the project's public token - the same one shown in the panel for every integration. It goes straight into the URL because it is not a secret.

Authentication

The private key can be supplied three ways, checked in this order:

1. the api_token query parameter,
2. the api_token form field in the request body,
3. the Authorization: Bearer header.

The header is the safest choice: query parameters end up in proxy and server logs, and a form field needs an application/x-www-form-urlencoded body, which is not what you would normally use to send JSON.

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, optionally gzip-compressed with a Content-Encoding: gzip header. When the body is compressed, the key cannot travel as a form field - the parser reads the compressed stream straight as JSON, so a field inside it is never read. With gzip the key always has to go into the URL or the header.

The smallest possible error report

The only required fields are the exception's type and value:

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

Everything else is optional, but each field adds something to the diagnosis in the panel: the stack trace (exception.values[0].stacktrace), the client name and version (sdk.name, sdk.version), the environment, operating system and runtime (contexts.os.*, contexts.runtime), the request context (request.url, request.method, request.headers), and user data (user.id, user.username, user.email, user.ip_address, user.agent).

The smallest possible transaction report

The only required field is a non-empty contexts.trace.data:

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

The first 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 control message"}]}}'

A 200 {"success": true} response means the event was accepted. Check the panel under Errors for the project the token points at.