Axiom
Overview

totimespan

You typically use totimespan when working with duration strings, numeric values representing time intervals, or other types that need to be converted to timespan format for duration calculations.

Usage#

Syntax#

totimespan(value)

Parameters#

Name Type Description
value dynamic The value to convert to timespan.

Returns#

If conversion is successful, the result is a timespan value. If conversion isn't successful, the result is null.

Conversion behavior#

The totimespan function converts values based on their type:

  • Integer/Float: Interpreted as nanoseconds. For example, 1000000000 represents one second.
  • String: Parsed as a duration string. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h", or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

Use case examples#

Convert numeric duration values to timespan format for duration-based analysis and filtering.

Query

['sample-http-logs']
| extend duration_span = totimespan(['req_duration_ms'] * 1000000)
| extend is_slow = duration_span > totimespan('1ms')
| where is_slow == true
| project _time, ['uri'], ['req_duration_ms'], duration_span, is_slow

Run in Playground

Output

_time uri req_duration_ms duration_span is_slow
Jun 24, 09:28:10 /api/users 1500 00:00:01.5000000 true

This example converts millisecond durations to timespan format and compares them to a threshold, enabling precise duration-based filtering and analysis.

Convert trace duration values to timespan format for duration analysis and percentile calculations.

Query

['otel-demo-traces']
| extend span_duration = totimespan(['duration'])
| extend is_slow_span = span_duration > totimespan('100ms')
| where is_slow_span == true
| project _time, ['trace_id'], ['service.name'], ['duration'], span_duration, is_slow_span

Run in Playground

Output

_time trace_id service.name duration span_duration is_slow_span
Jun 24, 09:28:10 abc123 frontend 150000000 00:00:00.1500000 true

This example converts trace durations to timespan format and identifies slow spans, enabling duration-based performance analysis of trace data.

Convert security event duration metrics to timespan format for time-based security analysis.

Query

['sample-http-logs']
| extend request_duration = totimespan(['req_duration_ms'] * 1000000)
| extend is_suspicious_duration = request_duration > totimespan('5ms')
| where is_suspicious_duration == true
| project _time, ['uri'], ['status'], ['req_duration_ms'], request_duration, is_suspicious_duration

Run in Playground

Output

_time uri status req_duration_ms request_duration is_suspicious_duration
Jun 24, 09:28:10 /admin 403 5500 00:00:05.5000000 true

This example converts request durations to timespan format and identifies suspiciously long security events, enabling duration-based security analysis and alerting.

  • todatetime: Converts input to datetime. Use todatetime for absolute time points, and totimespan for duration values.

Other query languages#

Splunk SPL users

In Splunk, you use time functions or duration calculations with numeric values. In APL, totimespan provides a direct way to convert values to timespan format for duration operations.

Splunk example

... | eval duration = duration_field

APL equivalent

... | extend duration = totimespan(duration_field)
ANSI SQL users

In standard SQL, you use INTERVAL types or duration functions to work with time spans. In APL, totimespan provides a simpler way to convert values to timespan format.

SQL example

SELECT INTERVAL '1' DAY AS duration FROM logs;

APL equivalent

['sample-http-logs']
| extend duration = totimespan('24h')

Updated

Was this page helpful?