Skip to main content

Function Library — Time

C.Time covers timestamp parsing and formatting for JavaScript scripts.

FunctionSignatureReturns
strptime(value, format, utc, strict)A Date, or null where the value does not match
strftime(date, format, utc)The formatted string
adjustTZ(epochSeconds, toZone, fromZone)The adjusted time in milliseconds
clamp(date, earliest, latest, fallback)The date, moved inside the range where it falls outside
timestampFinder(utc)An object with a find() method
timePartition(date, level)A YYYY/MM/DD path fragment
s3TimePartition(date, level)A prefixed path fragment

Details​

Parsing​

strptime() parses a string against a format and returns a Date. It returns null — not undefined — where the value does not match, so test with !== null.

The third argument selects UTC, and defaults to true. Pass false to interpret the value as local time.

The fourth argument enables strict matching. By default, input left over after the format is consumed is ignored; with strict set to true, trailing input causes the parse to fail. Use it when the same field can carry several formats and you are testing which one applies.

Parse a timestamp, falling back to a second format...

- script:
    lang: js
    source: |
        const raw = __e.logged_at;
        let t = C.Time.strptime(raw, '%Y-%m-%d %H:%M:%S', true, true);
        if (t === null) {
          t = C.Time.strptime(raw, '%d/%b/%Y:%H:%M:%S', true, true);
        }
        if (t !== null) {
          __e['@timestamp'] = t.toISOString();
        }

Formatting​

strftime() formats a Date, an epoch value or a parseable string. A number is read as Unix seconds, not milliseconds — this is the most common mistake with this function, and it matters because adjustTZ() returns milliseconds. Divide by 1,000 when passing one to the other.

Both a date it cannot parse and a missing format return undefined.

The format accepts the usual C-style tokens: %Y %m %d %H %M %S for the numeric components, %L and %f for fractional seconds, %a %A %b %B for day and month names, %p for AM/PM, %j for day of year, %s and %Q for epoch values, %Z and %z for the zone, and %% for a literal percent sign.

Time Zones​

adjustTZ() shifts an epoch value from one zone to another, returning milliseconds. The source zone defaults to UTC.

Zones are named with IANA identifiers — Europe/Istanbul, America/New_York, Australia/Melbourne. Abbreviations such as CET or PST are not accepted and yield undefined, as does a non-numeric epoch value.

Render a UTC timestamp in local time...

- script:
    lang: js
    source: |
        const ms = C.Time.adjustTZ(__e.epoch_seconds, 'Europe/Istanbul');
        if (ms !== undefined) {
          __e.local_time = C.Time.strftime(ms / 1000, '%Y-%m-%d %H:%M');
        }

Clamping​

clamp() constrains a date to a range, which is how events carrying an implausible timestamp are kept from distorting a time-series. A date before earliest becomes earliest, a date after latest becomes latest, and a date inside the range is returned unchanged.

Supply a fourth argument to substitute a specific value instead of the nearer bound. Any argument that will not parse yields undefined.

Finding a Timestamp​

timestampFinder() returns an object whose find() method extracts a timestamp from arbitrary text, trying several common layouts — ISO 8601, Apache common log format, US date-time, syslog without a year, date-only, and epoch values in seconds or milliseconds. It returns epoch milliseconds, or null where nothing matches.

Build the finder once and reuse it within the script:

const finder = C.Time.timestampFinder(true);
__e.parsed_at = finder.find(__e._raw);

Partitioning​

timePartition() produces a path fragment for date-based partitioning: YYYY/MM/DD by default, or YYYY/MM/DD/HH when passed 'h' as the second argument. Any other level returns undefined.

s3TimePartition() produces the same partitioning with a prefix on each component.

These are useful for computing an output path in a script; for routine partitioning of target output, the target's own path template is the better mechanism.