Time Shift

Date and Time Timezone

Synopsis

Shifts timestamps by specified amounts with timezone conversion.

Schema

- timeshift:
    field: <ident>
    amount: <string>
    unit: <string>
    target_field: <string>
    format: <string>
    timezone: <string>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing timestamp to shift
amount	Y	-	Shift amount as numeric string (positive or negative)
unit	Y	-	Time unit (seconds, minutes, hours, days, weeks, months, years)
target_field	N	Same as field	Target field to store shifted timestamp
format	N	RFC3339	Go time layout for the output. When the source field is a string it also governs parsing, replacing the auto-detected format list — so the stored value must match this layout exactly or the processor fails. It has no effect on parsing when the field is numeric
timezone	N	-	Target timezone for output
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if shift fails
ignore_missing	N	false	Skip processing if referenced field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

Shifts timestamps by specified amounts supporting various time units and timezone conversions. The processor handles multiple input formats and provides flexible output formatting options.

The processor accepts timestamps as RFC 3339, as Unix timestamps (integer or float, in seconds), and as several common date/time strings. With format unset it tries each known layout in turn, then falls back to reading the value as a Unix timestamp.

format is one setting doing two jobs. For a string field it is the input layout as well as the output layout, so the two cannot differ: format: "2006-01-02" reads 2024-01-15 and writes 2024-04-15, but fails outright on 2024-01-15T00:00:00Z. To reformat a string timestamp into a different layout, shift it here and convert with a separate Date step. A numeric field is unaffected — it is always read as a Unix timestamp, and format shapes only the output.

note

Time units support both singular and plural forms with common abbreviations: seconds (s, sec, secs), minutes (m, min, mins), hours (h, hr, hrs), days (d), weeks (w), months, and years (y). Fractional amounts are supported for precise time shifts.

For months and years, the processor handles variable lengths carefully. Months use approximate calculations (30.44 days per month) for fractional parts, while years use 365.25 days to account for leap years.

warning

Month and year calculations are approximate for fractional values. For precise date arithmetic, use whole number amounts or convert to days/hours for exact calculations.

Examples

Basic Time Shift

Shifting timestamp forward by 2 hours...	{ "event_time": "2024-01-15T10:30:00Z" } - timeshift: field: event_time amount: "2" unit: hours target_field: adjusted_time
adds 2 hours to timestamp:	{ "event_time": "2024-01-15T10:30:00Z", "adjusted_time": "2024-01-15T12:30:00Z" }

Timezone Conversion with Shift

Shifting time and converting timezone...	{ "utc_timestamp": "2024-01-15T10:30:00Z" } - timeshift: field: utc_timestamp amount: "-1" unit: days timezone: "America/New_York" target_field: local_yesterday
shifts to previous day in EST:	{ "utc_timestamp": "2024-01-15T10:30:00Z", "local_yesterday": "2024-01-14T05:30:00-05:00" }

Unix Timestamp Processing

Processing Unix timestamp with custom format...	{ "epoch_time": 1705312200 } - timeshift: field: epoch_time amount: "30" unit: minutes format: "2006-01-02 15:04:05" target_field: shifted_readable
formats shifted time as readable string:	{ "epoch_time": 1705312200, "shifted_readable": "2024-01-15 11:00:00" }

Negative Time Shift

Shifting timestamp backward for log correlation...	{ "log_timestamp": "2024-01-15T14:30:45.123Z" } - timeshift: field: log_timestamp amount: "-15" unit: seconds target_field: correlation_window
creates earlier timestamp for correlation:	{ "log_timestamp": "2024-01-15T14:30:45.123Z", "correlation_window": "2024-01-15T14:30:30.123Z" }

Fractional Time Units

Using fractional hours for precise shifts...	{ "meeting_time": "2024-01-15T09:00:00Z" } - timeshift: field: meeting_time amount: "1.5" unit: hours target_field: break_time
shifts by 1.5 hours, writing RFC 3339:	{ "meeting_time": "2024-01-15T09:00:00Z", "break_time": "2024-01-15T10:30:00Z" }

Monthly Scheduling

Calculating monthly report dates...	{ "report_date": "2024-01-15" } - timeshift: field: report_date amount: "3" unit: months timezone: "UTC" format: "2006-01-02" target_field: quarterly_date
the same layout reads the input and writes the result:	{ "report_date": "2024-01-15", "quarterly_date": "2024-04-15" }

Week-based Scheduling

Calculating weekly maintenance windows...	{ "last_maintenance": "2024-01-08T02:00:00Z" } - timeshift: field: last_maintenance amount: "2" unit: weeks target_field: next_maintenance timezone: "Europe/London"
schedules next maintenance in local time:	{ "last_maintenance": "2024-01-08T02:00:00Z", "next_maintenance": "2024-01-22T02:00:00Z" }

String Date Processing

Processing various string date formats...	{ "custom_date": "2024/01/15 14:30:00" } - timeshift: field: custom_date amount: "-7" unit: days format: "Jan 2, 2006 at 3:04pm" target_field: week_ago
parses and shifts with readable output:	{ "custom_date": "2024/01/15 14:30:00", "week_ago": "Jan 8, 2024 at 2:30pm" }