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	Output datetime format
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

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 in various formats including RFC3339, Unix timestamps (integer or float), and common date/time string formats. When no format is specified, it attempts to parse using common formats automatically.

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 format: "3:04PM MST"
shifts by 1.5 hours with time-only format:	{ "meeting_time": "2024-01-15T09:00:00Z", "break_time": "10:30AM UTC" }

Monthly Scheduling

Calculating monthly report dates...	{ "report_date": "2024-01-15T00:00:00Z" } - timeshift: field: report_date amount: "3" unit: months timezone: "UTC" format: "2006-01-02" target_field: quarterly_date
calculates quarterly report date:	{ "report_date": "2024-01-15T00:00:00Z", "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" }