README

This composer package allows to log data in CloudWatch, with auto-generated correlation id to follow the logs throughout all processes and their children.

⚙️ Installation

Install the latest version with

$ composer require arrowsphere/cloudwatch-logs

Request identifiers management

📖 Introduction

We manage 3 types of identifiers to help us identify our requests and follow their logs.

The request id, identified as ars-request-id, is the unique identifier for the current request. It is auto-generated and cannot be null.

The parent id, identified as ars-parent-id, is the identifier of the parent request, that directly called this one. It can be null if the current request is the originator of a process.

The correlation id, identified as ars-correlation-id, is the identifier of the originator request of the process.

Whenever an event is logged, we should have those 3 headers indicated in the logging context.

🔧 How to use

The header ids

The three header ids are automatically logged by the logger system provided by this package, however if you want to pass them through to other API calls, you'll have to access them by yourself.

You can access the headers by using class ArsHeaderManager.

The simplest way to use this class is to use static method ArsHeaderManager::initFromGlobals() with no argument, it works as a singleton, and will populate the ids with whatever is already present in the $_SERVER superglobal.

The $_SERVER superglobal will then contain all three ids (parent id being an empty string if there's none).

Here's an example of code to make use of the variables:

$arsHeaderManager = \ArrowSphere\CloudWatchLogs\Processor\ArsHeader\ArsHeaderManager::initFromGlobals();

$requestId = $arsHeaderManager->getRequestId();
$correlationId = $arsHeaderManager->getCorrelationId();
$parentId = $arsHeaderManager->getParentId();

// Now you have all three variables and can use them however you want.

The logger

This package provides a monolog handler for CloudWatch. To use it you'll have to instanciate it with the following parameters:

<?php
$sdkParams = [
    'credentials' => [
        'key' => 'your AWS access key',
        'secret' => 'your AWS secret access key',
    ],
    'region' => 'eu-west-1', // or any other AWS region
    'version' => 'latest', // or whatever seems pertinent here
];
$accountAlias = 'arrowsphere'; // this is the AWS account
$stage = 'prod'; // this is your stage
$application = 'xsp'; // this is your application name
$retentionDays = 30; // Days to keep logs, 90 by default
$batchSize = 1000; // How many log entries to store in memory before sending them to AWS, 10000 by default

$cloudWatchHandler = new \ArrowSphere\CloudWatchLogs\Handler\ArsCloudWatchHandler(
    $sdkParams,
    $accountAlias,
    $application,
    $stage,
    $retentionDays,
    $batchSize
);

The handler is now ready to be used, you can add it to your monolog logger with method pushHandler.

All logs you'll send to this logger will now be appended to CloudWatch, under the group name /{account_alias}/{stage}/{application}.

The logs are formatted by ArsJsonFormatter, which provides a unique format for ArrowSphere. This format is described here: https://confluence.arrowcloud.org/display/XSP/ArrowSphere+logs

This table is a reminder of the fields that can be used in the logs:

Here's an example of log:

{
  "type": "INFO",
  "message": "xAC API call to create a subscription",
  "tags": [
    "api_call",
    "xac"
  ],
  "entries": [],
  "ars": {
    "correlation": "00000000-0000-0000-0000-0000AAAA1111",
    "request": "11111111-1111-1111-1111-0000AAAA1111",
    "parent": ""
  },
  "context": {
    "request": {
      "baseUri": "https://xac.example.com/api",
      "endpointUri": "/subscription",
      "method": "POST",
      "body": {
        "customerRef": "XSP12345",
        "arrowspherePriceBandSku": "ABCD-1234"
      },
      "headers": {
        "AC-API-TOKEN": "***** (Obfuscated)",
        "Accept": "application/vnc.xac.v6+json"
      }
    },
    "response": {
      "httpStatusCode": 201,
      "body": {
        "subscriptionLineId": 12345
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    "extra": {
      "memoryUsage": "22 MB"
    }
  }
}

Please note that the logger uses ArsHeaderManager and provides the three header ids in the ars object as described above. This is handled by ArsHeaderProcessor.

📃 License

This package is made available under the MIT License (MIT). Please see License File for more information.