diff --git a/docs/sources/reference/timerange.md b/docs/sources/reference/timerange.md index 6a072589aa0..fda12261f3f 100755 --- a/docs/sources/reference/timerange.md +++ b/docs/sources/reference/timerange.md @@ -54,6 +54,16 @@ From Dashboard settings, click the Timepicker tab. From here you can specify the Grafana offers the ability to override the `now` value on a per dashboard basis. Most commonly, this feature is used to accommodate known delays in data aggregation to avoid null values. +### Time zone options +Starting in version 7.0, you can override the time zone used to display date and time values in a dashboard. + +With this feature, you can specify the local time zone of the service or system that you are monitoring. This can be helpful when monitoring a system or service that operates across several time zones. + +Apart from the standard [ISO 8601 time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) you can select the following options: + +* **Default**: The default selected time zone for the user profile or organization is used. If no time zone is specified for the user profile or the organization, then `Local browser time` is used. +* **Local browser time**: The time zone configured for the viewing user browser is used. This is usually the same time zone as set on the computer. + ## Panel time overrides and timeshift You can override the relative time range for individual panels, causing them to be different than what is selected in the Dashboard time picker in the upper right. This allows you to show metrics from different time periods or days at the same time. diff --git a/packages/grafana-data/src/datetime/common.ts b/packages/grafana-data/src/datetime/common.ts index 2c7625dddab..bdd291e87b3 100644 --- a/packages/grafana-data/src/datetime/common.ts +++ b/packages/grafana-data/src/datetime/common.ts @@ -1,17 +1,46 @@ import { TimeZone, DefaultTimeZone } from '../types/time'; +/** + * The type describing date and time options. Used for all the helper functions + * available to parse or format date and time values. + * + * @public + */ export interface DateTimeOptions { + /** + * Specify this if you want to override the timeZone used when parsing or formatting + * a date and time value. If no timeZone is set, the default timeZone for the current + * user is used. + */ timeZone?: TimeZone; } +/** + * The type to describe the time zone resolver function that will be used to access + * the default time zone of a user. + * + * @public + */ export type TimeZoneResolver = () => TimeZone | undefined; let defaultTimeZoneResolver: TimeZoneResolver = () => DefaultTimeZone; +/** + * Used by Grafana internals to set the {@link TimeZoneResolver} to access the current + * user timeZone. + * + * @internal + */ export const setTimeZoneResolver = (resolver: TimeZoneResolver) => { defaultTimeZoneResolver = resolver ?? defaultTimeZoneResolver; }; +/** + * Used within this package to get timeZone from an options value. If timezone + * is not set in the options, then a default timeZone is be resolved instead. + * + * @internal + */ export const getTimeZone = (options?: T): TimeZone => { return options?.timeZone ?? defaultTimeZoneResolver() ?? DefaultTimeZone; }; diff --git a/packages/grafana-data/src/datetime/formatter.ts b/packages/grafana-data/src/datetime/formatter.ts index 5d0034e0af7..d645a4e525b 100644 --- a/packages/grafana-data/src/datetime/formatter.ts +++ b/packages/grafana-data/src/datetime/formatter.ts @@ -5,28 +5,89 @@ import { DateTimeInput } from './moment_wrapper'; import { DEFAULT_DATE_TIME_FORMAT, MS_DATE_TIME_FORMAT } from './formats'; import { DateTimeOptions, getTimeZone } from './common'; +/** + * The type describing the options that can be passed to the {@link dateTimeFormat} + * helper function to control how the date and time value passed to the function is + * formatted. + * + * @public + */ export interface DateTimeOptionsWithFormat extends DateTimeOptions { + /** + * Specify a {@link https://momentjs.com/docs/#/displaying/format | momentjs} format to + * use a custom formatting pattern of the date and time value. If no format is set, + * then {@link DEFAULT_DATE_TIME_FORMAT} is used. + */ format?: string; + + /** + * Set this value to `true` if you want to include milliseconds when formatting date and time + * values in the default {@link DEFAULT_DATE_TIME_FORMAT} format. + */ defaultWithMS?: boolean; } -export type DateTimeFormatter = ( - dateInUtc: DateTimeInput, - options?: T -) => string; +type DateTimeFormatter = (dateInUtc: DateTimeInput, options?: T) => string; +/** + * Helper function to format date and time according to the specified options. If no options + * are supplied, then default values are used. For more details, see {@link DateTimeOptionsWithFormat}. + * + * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc. + * @param options + * + * @public + */ export const dateTimeFormat: DateTimeFormatter = (dateInUtc, options?) => toTz(dateInUtc, getTimeZone(options)).format(getFormat(options)); +/** + * Helper function to format date and time according to the standard ISO format e.g. 2013-02-04T22:44:30.652Z. + * If no options are supplied, then default values are used. For more details, see {@link DateTimeOptionsWithFormat}. + * + * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc. + * @param options + * + * @public + */ export const dateTimeFormatISO: DateTimeFormatter = (dateInUtc, options?) => toTz(dateInUtc, getTimeZone(options)).format(); +/** + * Helper function to return elapsed time since passed date. The returned value will be formatted + * in a human readable format e.g. 4 years ago. If no options are supplied, then default values are used. + * For more details, see {@link DateTimeOptions}. + * + * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc. + * @param options + * + * @public + */ export const dateTimeFormatTimeAgo: DateTimeFormatter = (dateInUtc, options?) => toTz(dateInUtc, getTimeZone(options)).fromNow(); +/** + * Helper function to format date and time according to the Grafana default formatting, but it + * also appends the time zone abbreviation at the end e.g. 2020-05-20 13:37:00 CET. If no options + * are supplied, then default values are used. For more details please see {@link DateTimeOptions}. + * + * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc. + * @param options + * + * @public + */ export const dateTimeFormatWithAbbrevation: DateTimeFormatter = (dateInUtc, options?) => toTz(dateInUtc, getTimeZone(options)).format(`${DEFAULT_DATE_TIME_FORMAT} z`); +/** + * Helper function to return only the time zone abbreviation for a given date and time value. If no options + * are supplied, then default values are used. For more details please see {@link DateTimeOptions}. + * + * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc. + * @param options + * + * @public + */ export const timeZoneAbbrevation: DateTimeFormatter = (dateInUtc, options?) => toTz(dateInUtc, getTimeZone(options)).format('z'); diff --git a/packages/grafana-data/src/datetime/parser.ts b/packages/grafana-data/src/datetime/parser.ts index 3d50bf971ac..ea505168260 100644 --- a/packages/grafana-data/src/datetime/parser.ts +++ b/packages/grafana-data/src/datetime/parser.ts @@ -5,15 +5,38 @@ import { DateTimeOptions, getTimeZone } from './common'; import { parse, isValid } from './datemath'; import { lowerCase } from 'lodash'; +/** + * The type that describes options that can be passed when parsing a date and time value. + * @public + */ export interface DateTimeOptionsWhenParsing extends DateTimeOptions { + /** + * If the input is a Grafana quick date, e.g. now-6h, then you can specify this to control + * whether the last part of the date and time value is included or excluded. + * + * Example: now-6h and the current time is 12:20:00 if roundUp is set to true + * the returned DateTime value will be 06:00:00. + */ roundUp?: boolean; } -export type DateTimeParser = ( - value: DateTimeInput, - options?: T -) => DateTime; +type DateTimeParser = (value: DateTimeInput, options?: T) => DateTime; +/** + * Helper function to parse a number, text or Date to a DateTime value. If a timeZone is supplied the incoming value + * is parsed with that timeZone as a base. The only exception to this is if the passed value is in a UTC-based + * format. Then it will use UTC as the base. Examples on UTC-based values are Unix epoch and ISO formatted strings. + * + * It can also parse the Grafana quick date and time format, e.g. now-6h will be parsed as Date.now() - 6 hours and + * returned as a valid DateTime value. + * + * If no options are supplied, then default values are used. For more details please see {@link DateTimeOptions}. + * + * @param value - should be a parsable date and time value + * @param options + * + * @public + */ export const dateTimeParse: DateTimeParser = (value, options?): DateTime => { if (isDateTime(value)) { return value;