totimespan

This page explains how to use the totimespan function in APL.

Use the totimespan function to convert various data types to a timespan value representing a duration. This is helpful when you need to normalize duration values from different sources into timespan format for time-based calculations, comparisons, or aggregations.

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.