Instalación - API REST

Antes de empezar, crea un proyecto en el panel de DockRay. En sus ajustes encontrarás el token del proyecto - el identificador público que forma parte de la URL de ingesta - y en la pestaña Claves de API generarás una clave privada. La clave se muestra una sola vez, al generarla: DockRay guarda únicamente su hash. Si todavía no tienes un proyecto, empieza por Primeros pasos.

Dos endpoints

{token} en la dirección es el token público del proyecto - el mismo que se ve en el panel para cualquier integración. Va directo en la URL porque no es un secreto.

Autenticación

La clave privada se puede pasar de tres formas, comprobadas en este orden:

1. el parámetro de consulta api_token,
2. el campo de formulario api_token en el cuerpo de la petición,
3. la cabecera Authorization: Bearer.

La cabecera es la opción más segura: los parámetros de la URL acaban en los registros de proxies y servidores, y un campo de formulario necesita un cuerpo application/x-www-form-urlencoded, que no es lo habitual para enviar 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"
        }
      ]
    }
  }'

Cuerpo de la petición

JSON, opcionalmente comprimido con gzip y con la cabecera Content-Encoding: gzip. Cuando el cuerpo está comprimido, la clave no puede viajar como campo de formulario: el analizador lee el flujo comprimido directamente como JSON, así que un campo dentro de él nunca se lee. Con gzip la clave siempre tiene que ir en la URL o en la cabecera.

El informe de error mínimo

Los únicos campos obligatorios son el tipo y el valor de la excepción:

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

Todo lo demás es opcional, pero cada campo añade algo al diagnóstico en el panel: la pila de llamadas (exception.values[0].stacktrace), el nombre y la versión del cliente (sdk.name, sdk.version), el entorno, el sistema operativo y el runtime (contexts.os.*, contexts.runtime), el contexto de la petición (request.url, request.method, request.headers) y los datos del usuario (user.id, user.username, user.email, user.ip_address, user.agent).

El informe de transacción mínimo

El único campo obligatorio es un contexts.trace.data no vacío:

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

La primera prueba

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":"Mensaje de control DockRay"}]}}'

Una respuesta 200 {"success": true} significa que el evento fue aceptado. Comprueba el panel, en la sección Errores del proyecto al que apunta el token.