ALB Log Parser

Common errors

• TypeError: parse is not a function

  cause Attempting to destructure a default export, e.g., `const { parse } = require('alb-log-parser');` or `import { parse } from 'alb-log-parser';`, when the module exports the function directly as the default export.
  fix Use `const parse = require('alb-log-parser');` for CommonJS or `import parse from 'alb-log-parser';` for ESM to correctly import the default exported function.

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ES Module (`.mjs` file or `"type": "module"` in `package.json`) context.
  fix Switch to ESM import syntax: `import parse from 'alb-log-parser';` if your project is configured for ES Modules.

Warnings

• gotcha This package is currently in `0.0.x` versioning, indicating a non-stable API. Minor version updates may introduce breaking changes without strictly adhering to semantic versioning guidelines.
  Fix: Rely on specific patch versions (e.g., `~0.0.8` instead of `^0.0.8`) or thoroughly test updates before deploying to production environments.
• gotcha As a fork of `elb-log-parser`, this package's maintenance and feature development are independent. It may not keep pace with future changes to AWS ALB log formats or new features in the original `elb-log-parser` or other, more actively maintained ALB log parsers in different languages.
  Fix: Periodically review AWS documentation for ALB log format changes and verify library behavior against new log entries. Consider contributing upstream or migrating if official support or more active development becomes critical.
• breaking In `v0.0.8`, the parser was updated to interpret fields with the value `"-1"` as a numeric `-1` instead of a string `"-"`. While intended as a correction, this changes the data type and value for these specific fields, potentially affecting existing data processing pipelines or schema expectations.
  Fix: Update consumers of the parsed log data to expect numeric `-1` for relevant fields where `"-"` previously indicated absence or a non-numeric value. Review pipelines that perform strict type checking or rely on the previous string representation.

Install

• npm install alb-log-parser npm
• yarn add alb-log-parser yarn
• pnpm add alb-log-parser pnpm

Imports

• parse
  wrong:

  const { parse } = require('alb-log-parser');

  correct:

  const parse = require('alb-log-parser');

  This package primarily uses CommonJS `module.exports` to export the `parse` function directly. Attempting to destructure it will result in `undefined`.
• parse
  wrong:

  import { parse } from 'alb-log-parser';

  correct:

  import parse from 'alb-log-parser';

  While primarily a CommonJS package, modern Node.js environments configured for ESM can import it as a default ESM import. Named imports like `import { parse }` will not work.

Quickstart

This quickstart demonstrates how to install `alb-log-parser` and use its primary `parse` function to convert a raw ALB access log string into a structured JavaScript object. It shows both installation and basic API usage with a sample log line.

npm install alb-log-parser
// or npm install -g alb-log-parser for global CLI usage

const parse = require('alb-log-parser');

const albLogLine = 'http 2020-08-27T16:35:00.166351Z app/my-loadbalancer/50dc6c495c0c9188 192.168.131.39:2817 192.168.201.251:80 0.000 0.440 0.000 200 200 1107 11912 "GET http://example.com:80/path?foo=bar&baz=bak HTTP/1.1" "Fake/1.0.0 (Linux)" - - arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/my-tg/ffffffffffffffff "Self=1-00000000-111111111111111111111111;Root=1-00000000-222222222222222222222222" "-" "-" 0 2020-08-27T16:34:59.725000Z "forward" "-" "-" "192.168.201.251:80" "200" "-" "-"';

const parsedLog = parse(albLogLine);
console.log(JSON.stringify(parsedLog, null, 2));

// Example for accessing specific fields
console.log(`
Client IP: ${parsedLog.client}`)
console.log(`Request Method: ${parsedLog.request_method}`)
console.log(`Target Status Code: ${parsedLog.target_status_code}`)