\| where method == "GET" and \_time > ago(24h) | ## Get n events or rows for inspection APL log queries also support `take` as an alias to `limit`. In Splunk, if the results are ordered, `head` returns the first n results. In APL, `limit` isn’t ordered, but it returns the first n rows that are found. | Product | Operator | Example | | ------- | -------- | ---------------------------------------- | | Splunk | head | Sample.Logs=330009.2
\| head 100 | | APL | limit | \['sample-htto-logs']
\| limit 100 | ## Get the first *n* events or rows ordered by a field or column For the bottom results, in Splunk, use `tail`. In APL, specify ordering direction by using `asc`. | Product | Operator | Example | | :------ | :------- | :------------------------------------------------------------------ | | Splunk | head | Sample.Logs="33009.2"
\| sort Event.Sequence
\| head 20 | | APL | top | \['sample-http-logs']
\| top 20 by method | ## Extend the result set with new fields or columns Splunk has an `eval` function, but it’s not comparable to the `eval` operator in APL. Both the `eval` operator in Splunk and the `extend` operator in APL support only scalar functions and arithmetic operators. | Product | Operator | Example | | :------ | :------- | :------------------------------------------------------------------------------------ | | Splunk | eval | Sample.Logs=330009.2
\| eval state= if(Data.Exception = "0", "success", "error") | | APL | extend | \['sample-http-logs']
\| extend Grade = iff(req\_duration\_ms >= 80, "A", "B") | ## Rename APL uses the `project` operator to rename a field. In the `project` operator, a query can take advantage of any indexes that are prebuilt for a field. Splunk has a `rename` operator that does the same. | Product | Operator | Example | | :------ | :------- | :-------------------------------------------------------------- | | Splunk | rename | Sample.Logs=330009.2
\| rename Date.Exception as execption | | APL | project | \['sample-http-logs']
\| project updated\_status = status | ## Format results and projection Splunk uses the `table` command to select which columns to include in the results. APL has a `project` operator that does the same and [more](/apl/tabular-operators/project-operator). | Product | Operator | Example | | :------ | :------- | :--------------------------------------------------- | | Splunk | table | Event.Rule=330009.2
\| table rule, state | | APL | project | \['sample-http-logs']
\| project status, method | Splunk uses the `field -` command to select which columns to exclude from the results. APL has a `project-away` operator that does the same. | Product | Operator | Example | | :------ | :--------------- | :-------------------------------------------------------------- | | Splunk | **fields -** | Sample.Logs=330009.2\`
\| fields - quota, hightest\_seller | | APL | **project-away** | \['sample-http-logs']
\| project-away method, status | ## Aggregation See the [list of summarize aggregations functions](/apl/aggregation-function/statistical-functions) that are available. | Splunk operator | Splunk example | APL operator | APL example | | :-------------- | :------------------------------------------------------------- | :----------- | :----------------------------------------------------------------------- | | **stats** | search (Rule=120502.\*)
\| stats count by OSEnv, Audience | summarize | \['sample-http-logs']
\| summarize count() by content\_type, status | ## Sort In Splunk, to sort in ascending order, you must use the `reverse` operator. APL also supports defining where to put nulls, either at the beginning or at the end. | Product | Operator | Example | | :------ | :------- | :------------------------------------------------------------- | | Splunk | sort | Sample.logs=120103
\| sort Data.Hresult
\| reverse | | APL | order by | \['sample-http-logs']
\| order by status desc | Whether you’re just starting your transition or you’re in the thick of it, this guide can serve as a helpful roadmap to assist you in your journey from Splunk to Axiom Processing Language. Dive into the Axiom Processing Language, start converting your Splunk queries to APL, and explore the rich capabilities of the Query tab. Embrace the learning curve, and remember, every complex query you master is another step forward in your data analytics journey. # Axiom Processing Language (APL) APL is a query language that is perfect for getting deeper insights from your data. Whether logs, or metrics, APL provides the flexibility to filter, and summarize your data exactly the way you need it. ## Introduction The Axiom Processing Language (APL) is a query language that is perfect for getting deeper insights from your data. Whether logs, events, analytics, or similar, APL provides the flexibility to filter, manipulate, and summarize your data exactly the way you need it. ## Get started Go to the Query tab and click one of your datasets to get started. The APL editor has full auto-completion so you can poke around or you can get a better understanding of all the features by using the reference menu to the left of this page. ## APL Query Structure At a minimum, a query consists of source data reference (name of a dataset) and zero or more query operators applied in sequence. Individual operators are delimited using the pipe character (`|`). APL query has the following structure: ```kusto DataSource | operator ... | operator ... ``` Where: * DataSource is the name of the dataset you want to query * Operator is a function that will be applied to the data Let’s look at an example query. ```kusto ['github-issue-comment-event'] | extend bot = actor contains "-bot" or actor contains "[bot]" | where bot == true | summarize count() by bin_auto(_time), actor ``` The query above begins with reference to a dataset called **github-issue-comment-event** and contains several operators, [extend](/apl/tabular-operators/extend-operator), [where](/apl/tabular-operators/where-operator), and [summarize](/apl/tabular-operators/summarize-operator), each separated by a `pipe`. The extend operator creates the **bot** column in the returned result, and sets its values depending on the value of the actor column, the **where** operator filters out the value of the **bot** to a branch of rows and then produce a chart from the aggregation using the **summarize** operator. The most common kind of query statement is a tabular expression statement. Tabular statements contain operators, each of which starts with a tabular `input` and returns a tabular `output.` * Explore the [tabular operators](/apl/tabular-operators/extend-operator) we support. * Check out our [entity names and identifier naming rules](/apl/entities/entity-names). Axiom Processing Language supplies a set of system [data types](/apl/data-types/scalar-data-types) that define all the types of [data](/apl/data-types/null-values) that can be used with Axiom Processing Language. # Set statement The set statement is used to set a query option in your APL query. The `set` statement is used to set a query option. Options enabled with the `set` statement only have effect for the duration of the query. The `set` statement specified will affect how your query is processed and the returned results. ## Syntax ```kusto set OptionName=OptionValue ``` ## Strict types The `stricttypes` query option lets you specify only the exact type of the data type declaration needed in your query, or a **QueryFailed** error will be thrown. ## Example ```kusto set stricttypes; ['Dataset'] | where number == 5 ``` # Special field attributes This page explains how to implement special fields within APL queries to enhance the functionality and interactivity of datasets. Use these fields in APL queries to add unique behaviors to the Axiom user interface. ## Add link to table * Name: `_row_url` * Type: string * Description: Define the URL to which the entire table links. * APL query example: `extend _row_url = 'https://axiom.co/'` * Expected behavior: Make rows clickable. When clicked, go to the specified URL. If you specify a static string as the URL, all rows link to that page. To specify a different URL for each row, use an dynamic expression like `extend _row_url = strcat('https://axiom.co/', uri)` where `uri` is a field in your data. ## Add link to values in a field * Name: `_FIELDNAME_url` * Type: string * Description: Define a URL to which values in a field link. * APL query example: `extend _website_url = 'https://axiom.co/'` * Expected behavior: Make values in the `website` field clickable. When clicked, go to the specified URL. Replace `FIELDNAME` with the actual name of the field. ## Add tooltip to values in a field * Name: `_FIELDNAME_tooltip` * Type: string * Description: Define text to be displayed when hovering over values in a field. * Example Usage: `extend _errors_tooltip = 'Number of errors'` * Expected behavior: Display a tooltip with the specified text when the user hovers over values in a field. Replace `FIELDNAME` with the actual name of the field. ## Add description to values in a field * Name: `_FIELDNAME_description` * Type: string * Description: Define additional information to be displayed under the values in a field. * Example Usage: `extend _diskusage_description = 'Current disk usage'` * Expected behavior: Display additional text under the values in a field for more context. Replace `FIELDNAME` with the actual name of the field. ## Example The example APL query below adds a tooltip and a description to the values of the `status` field. Clicking one of the values in this field leads to a page about status codes. ```apl ['http-logs'] | extend _status_tooltip = "The status of the HTTP request is the response code from the server. It shows if an HTTP request has been successfully completed." | extend _status_description = "This is the status of the HTTP request." | extend _status_url = "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" ``` # Array functions Learn how to use and combine different mathematical functions in APL ## Array Functions * Most of the `array` functions are used with the `dynamic array` function. Dynamic arrays lets you insert an element if there is no more space left for the new element. It allows you to add or remove elements, allocates memory at run time, and can be modified with any `array` function. * In APL, a `dynamic` array expands as you add more objects. So you don’t need to determine the size ahead of time, and also lets you write `functions` that are reusable. | **Function Name** | **Description** | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [array\_concat()](#array-concat) | Concatenates a number of dynamic arrays to a single array. | | [array\_iff()](#array-iff) | Returns a new array containing elements from the input array that satisfy the condition. | | [array\_index\_of()](#array-index-of) | Searches the array for the specified item, and returns its position. | | [array\_length()](#array-length) | Calculates the number of elements in a dynamic array. | | [array\_reverse()](#array-reverse) | Reverses the order of the elements in a dynamic array. | | [array\_rotate\_left](#array-rotate-left) | Rotates values inside a `dynamic` array to the left. | | [array\_rotate\_right](#array-rotate-right) | Rotates values inside a `dynamic` array to the right. | | [array\_select\_dict()](#array-select-dict) | Selects a dictionary from an array of dictionaries. | | [array\_shift\_left()](#array-shift-left) | Shifts the values inside a `dynamic` array to the left. | | [array\_shift\_right()](#array-shift-right) | shifts values inside an array to the right. | | [array\_slice()](#array-slice) | Extracts a slice of a dynamic array. | | [array\_split()](#array-split) | Splits an array to multiple arrays according to the split indices and packs the generated array in a dynamic array. | | [array\_sum()](#array-sum) | Calculates the sum of elements in a dynamic array. | | [isarray()](#isarray) | Checks whether a value is an array. | | [pack\_array()](#pack-array) | Packs all input values into a dynamic array. | Each argument has a **required** section which is denoted with `required` or `optional` * If it’s denoted by `required` it means the argument must be passed into that function before it'll work. * if it’s denoted by `optional` it means the function can work without passing the argument value. ## array\_concat() Concatenates a number of dynamic arrays to a single array. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ----------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------ | | arr1...arrN | dynamic | Required | Input arrays to be concatenated into a dynamic array. All arguments must be dynamic arrays | ### Returns Dynamic array of arrays with arr1, arr2, ... , arrN. ### Examples ```kusto array_concat(array ...) ``` ```kusto ['github-issues-event'] | extend array1 = dynamic([{"name": "status", "color": "ededed", "description": ""}]) | extend array2 = dynamic([{"name": "puffer-ai-hpc-portal", "color": "ededed", "description": ""}]) | extend concatenate = array_concat(array1, array2) | project concatenate ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27github-issues-event%27%5D%5Cn%7C%20extend%20array1%20%3D%20dynamic%28%5B%7B%27name%27%3A%20%27status%27%2C%20%27color%27%3A%20%27ededed%27%2C%20%27description%27%3A%20%27%27%7D%5D%29%5Cn%7C%20extend%20array2%20%3D%20dynamic%28%5B%7B%27name%27%3A%20%27puffer-ai-hpc-portal%27%2C%20%27color%27%3A%20%27ededed%27%2C%20%27description%27%3A%20%27%27%7D%5D%29%5Cn%7C%20extend%20concatenate%20%3D%20array_concat%28array1%2C%20array2%29%5Cn%7C%20project%20concatenate%22%7D) * Result ```json { "concatenate": [ { "name": "status", "description": "", "color": "ededed" }, { "name": "puffer-ai-hpc-portal", "description": "", "color": "ededed" } ] } ``` ```kusto ['github-issues-event'] | extend array1 = dynamic([{"app": "App1", "status": "running", "method": "GET"}]) | extend array2 = dynamic([{"app": "App2", "status": "stopped", "method": "POST"}]) | extend concatenatedLogs = array_concat(array1, array2) | project concatenatedLogs ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27github-issues-event%27%5D%5Cn%7C%20extend%20array1%20%3D%20dynamic%28%5B%7B%27app%27%3A%20%27App1%27%2C%20%27status%27%3A%20%27running%27%2C%20%27method%27%3A%20%27GET%27%7D%5D%29%5Cn%7C%20extend%20array2%20%3D%20dynamic%28%5B%7B%27app%27%3A%20%27App2%27%2C%20%27status%27%3A%20%27stopped%27%2C%20%27method%27%3A%20%27POST%27%7D%5D%29%5Cn%7C%20extend%20concatenatedLogs%20%3D%20array_concat%28array1%2C%20array2%29%5Cn%7C%20project%20concatenatedLogs%22%7D) * Result ```json { "concatenatedLogs": [ { "app": "App1", "status": "running", "method": "GET" }, { "app": "App2", "status": "stopped", "method": "POST" } ] } ``` ## array\_iff() Returns a new array containing elements from the input array that satisfy the condition. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ---------------- | -------- | ------------------------ | ---------------------------------------------------------------------------------------------------- | | condition\_array | dynamic | Required | Input array of boolean or numeric values | | when\_true | | Required | Input array of values - the result value(s) when the corresponding value of ConditionArray is true. | | when\_false | | Required | Input array of values - the result value(s) when the corresponding value of ConditionArray is false. | ### Returns Dynamic array of the values taken either from the when\_true or when\_false \[array] values, according to the corresponding value of the Condition array. ### Examples ```kusto array_iff(Condition_array, when_true, when_false) ``` ```kusto ['github-issues-event'] | extend return_array = array_iff(dynamic([true,false,true]), dynamic([4,2,1]), dynamic([7,8,4])) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20extend%20return_array%20%3D%20array_iff%28dynamic%28%5Btrue%2Cfalse%2Ctrue%5D%29%2C%20dynamic%28%5B4%2C2%2C1%5D%29%2C%20dynamic%28%5B7%2C8%2C4%5D%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "return_array": [4, 8, 1] } ``` ## array\_index\_of() Searches the array for the specified item, and returns its position. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ------------- | --------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | array | array | Required | Input array to search. | | lookup\_value | scalar | Required | The value should be of type `long`, `integer`, `double`, `datetime`, `timespan`, or `string`. | | start\_index | number | Optional | Search start position. A negative value will offset the starting search value from the end of the array by `abs(start_index) steps`.. | | length | number | Optional | Number of values to examine. A value of `-1` means unlimited length. | | occurrence | The number of the occurrence. Default 1 | No | | ### Returns Zero-based index position of lookup. Returns `-1` if the value isn’t found in the array. For irrelevant inputs (occurrence \< 0 or length \< -1) - returns null. ### Examples ```kusto array_index_of(array, value, [start], [length], [occurrence]) ``` ```kusto ['github-issues-event'] | extend index_of_array = array_index_of(dynamic(["this", "is", "an", "example", "an", "example"]), "pn") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?qid=ftntZpvUx5N-s2e5ft) * Result ```json { "index_of_array": -1 } ``` ## array\_length() Calculates the number of elements in a dynamic array. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | --------------- | | array | dynamic | Required | A dynamic value | ### Returns The number of elements in array, or null if array is not an array. ### Examples ```kusto array_length(array) ``` ```kusto ['github-issues-event'] | project return_length = array_length(labels) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20return_length%20%3D%20array_length%28labels%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "return_length": 2 } ``` ## array\_reverse() Reverses the order of the elements in a dynamic array. ### Arguments * array: Input array to reverse. ### Returns An array that contains exactly the same elements as the input array, but in reverse order. ### Examples ```kusto array_reverse(array) ``` ```kusto ['github-issues-event'] | project reversed_array = array_reverse(labels) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20reversed_array%20%3D%20array_reverse%28labels%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "reversed_array": [ { "name": "axiom", "color": "d73a4a", "description": "Axiom observability data" } ] } ``` ## array\_rotate\_left() Rotates values inside a `dynamic` array to the left. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ------------- | -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | array | dynamic | Required | Input array to rotate, must be dynamic array. | | rotate\_count | integer | Required | Number of positions that array elements will be rotated to the left. If the value is negative, the elements will be rotated to the right. | ### Returns Dynamic array containing the same amount of the elements as in original array, where each element was rotated according to rotate\_count. ### Examples ```kusto array_rotate_left(array, rotate_count) ``` ```kusto ['github-issues-event'] | project rotate_array_left = array_rotate_left(dynamic([1,2,3,4,5]), 1) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20rotate_array_left%20%3D%20array_rotate_left%28dynamic%28%5B1%2C2%2C3%2C4%2C5%5D%29%2C%201%29%22%7D) * Result ```json { "rotate_array_left": [2, 3, 4, 5, 1] } ``` ## array\_rotate\_right() Rotates values inside a `dynamic` array to the right. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ------------- | -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | array | dynamic | Required | Input array to rotate, must be dynamic array. | | rotate\_count | integer | Required | Number of positions that array elements will be rotated to the right. If the value is negative, the elements will be rotated to the Left. | ### Returns Dynamic array containing the same amount of the elements as in the original array, where each element was rotated according to rotate\_count. ### Examples ```kusto array_rotate_right(array, rotate_count) ``` ```kusto ['github-issues-event'] | project rotate_array_right = array_rotate_right(dynamic([1,2,3,4,5]), 1) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20rotate_array_right%20%3D%20array_rotate_right%28dynamic%28%5B1%2C2%2C3%2C4%2C5%5D%29%2C%201%29%22%7D) * Result ```json { "rotate_array_right": [5, 1, 2, 3, 4] } ``` ## array\_select\_dict() Selects a dictionary from an array of dictionaries. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | --------------------------------------------------- | | array | dynamic | Required | Input array of dictionaries, must be dynamic array. | | key | string | Required | Key to use for selection in of the dictionaries. | | value | scalar | Required | Value of the selected key to create a match. | ### Returns The first dictionary in the array that has a key and value match to the parameters or null if none. If a value in the array is not a dictionary, it will be ignored. ### Examples ```kusto array_select_dict(array, "search key", "matching value") ``` ```kusto datatable(a: dynamic)[dynamic([{"key": 5, "extra": "data", ""}, {"key": 6, "extra": "other_data", ""}])] | project selected = array_select_dict(a, "key", 5) ``` * Result ```json { "selected": dynamic({"key": 5, "extra": "data"}) } ``` ## array\_shift\_left() Shifts the values inside a `dynamic` array to the left. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------------- | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | array | dynamic | Required | Input array to rotate, must be dynamic array. | | shift\_count | integer | Required | Number of positions that array elements will be shifted to the left. If the value is negative, the elements will be shifted to the right. | | default\_value | scalar | Required | Value used for inserting elements instead of the ones that were shifted and removed. The default is null or an empty string depending on the array type. | ### Returns Dynamic array containing the same number of elements as in the original array. Each element has been shifted according to shift\_count ### Examples ```kusto array_shift_left(array, shift_count [, default_value ]) ``` ```kusto ['github-issues-event'] | project shift_array_left = array_shift_left(dynamic([1,2,3,4,5]), 1) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20shift_array_left%20%3D%20array_shift_left%28dynamic%28%5B1%2C2%2C3%2C4%2C5%5D%29%2C%201%29%22%7D) * Result ```json { "shift_array_left": [2, 3, 4, 5, null] } ``` ## array\_shift\_right() shifts values inside an array to the right. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------------- | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | array | dynamic | Required | Input array to rotate, must be dynamic array. | | shift\_count | integer | Required | Number of positions that array elements will be shifted to the right. If the value is negative, the elements will be shifted to the left. | | default\_value | scalar | Required | Value used for inserting elements instead of the ones that were shifted and removed. The default is null or an empty string depending on the array type. | ### Returns Dynamic array containing the same amount of the elements as in the original array. Each element has been shifted according to shift\_count. New elements that are added instead of the removed elements will have a value of default\_value. ### Examples ```kusto array_shift_right(array, shift_count [, default_value ]) ``` ```kusto ['github-issues-event'] | project shift_array_right = array_shift_right(dynamic([1,2,3,4,5]), 1) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20shift_array_right%20%3D%20array_shift_right%28dynamic%28%5B1%2C2%2C3%2C4%2C5%5D%29%2C%201%29%22%7D) * Result ```json { "shift_array_right": [null, 1, 2, 3, 4] } ``` ## array\_slice() Extracts a slice of a dynamic array. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ------------ | -------- | ------------------------ | ---------------------------------------------------------------------------------------------- | | array | dynamic | Required | Input array to extract the slice. | | shift\_count | number | Required | Start index of the slice (inclusive). Negative values are converted to `array_length`+`start`. | | end | number | Required | Last index of the slice. (inclusive). Negative values are converted to `array_length`+`end`. | ### Returns Dynamic array of the values in the range \[start..end] from array. ### Example ```kusto array_slice(array, start, end) ``` ```kusto ['github-issues-event'] | project slice_array = array_slice(dynamic([1,2,3]), 1, 2) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20slice_array%20%3D%20array_slice%28dynamic%28%5B1%2C2%2C3%5D%29%2C%201%2C%202%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "slice_array": [2] } ``` ## array\_split() Splits an array to multiple arrays according to the split indices and packs the generated array in a dynamic array. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | array | dynamic | Required | Array to split. | | indices | integer | Required | Split indices (zero based). This can be a single integer or a dynamic array of integers. Negative values are converted to `array_length` + `value`. | ### Returns Dynamic array containing `N+1` arrays with the values in the range \[0..1,2),from array, where **N** is the number of input indices. ### Examples ```kusto array_split(array, indices) ``` ```kusto ['github-issues-event'] | project split_array = array_split(dynamic([1,2,3,4,5]), 4) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20split_array%20%3D%20array_split%28dynamic%28%5B1%2C2%2C3%2C4%2C5%5D%29%2C%204%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "split_array": [[1, 2, 3, 4], [5]] } ``` ## array\_sum() Calculates the sum of elements in a dynamic array. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------------------------ | | array | dynamic | Required | Array that will be used in the input | ### Returns Double type value with the sum of the elements of the array. ### Examples ```kusto array_sum(array) ``` ```kusto ['github-issues-event'] | project sum_array = array_sum(dynamic([2,5,6])) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20sum_array%20%3D%20array_sum%28dynamic%28%5B2%2C5%2C6%5D%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) ## isarray() Returns a Boolean value indicating whether a variable is an array. It determines whether the passed value is an Array. ### Arguments * Expression: input value passed to the function. ### Returns Returns `True` if the expression is an array; otherwise, it returns `False`. ### Examples ```kusto isarray(expression) ``` ```kusto ['github-issues-event'] | project is_array = isarray( ['milestone.creator'] ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20%20is_array%20%3D%20isarray%28%20%5B%27milestone.creator%27%5D%20%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "is_array": false } ``` ## pack\_array() Packs all input values into a dynamic array. ### Arguments * Expression: Input expression value to be packed into a dynamic array. ### Returns Dynamic array which includes the values of Expr1, Expr2, ... , ExprN. ### Examples ```kusto pack_array(value, ...) ``` ```kusto ['github-issues-event'] | project packed_array = pack_array( creator, ['milestone.creator'] ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20packed_array%20%3D%20pack_array%28%20creator%2C%20%5B%27milestone.creator%27%5D%20%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "packed_array": ["axiomhq", "next-axiom"] } ``` # Conditional functions Learn how to use and combine different conditional functions in APL ## Conditional functions | **Function Name** | **Description** | | ----------------- | ----------------------------------------------------------------------------------------------------------- | | [case()](#case) | Evaluates a list of conditions and returns the first result expression whose condition is satisfied. | | [iff()](#iff) | Evaluates the first argument (the predicate), and returns the value of either the second or third arguments | ## case() Evaluates a list of conditions and returns the first result whose condition is satisfied. ### Arguments * condition: An expression that evaluates to a Boolean. * result: An expression that Axiom evaluates and returns the value if its condition is the first that evaluates to true. * nothingMatchedResult: An expression that Axiom evaluates and returns the value if none of the conditional expressions evaluates to true. ### Returns Axiom returns the value of the first result whose condition evaluates to true. If none of the conditions is satisfied, Axiom returns the value of `nothingMatchedResult`. ### Example ```kusto case(condition1, result1, condition2, result2, condition3, result3, ..., nothingMatchedResult) ``` ```kusto ['sample-http-logs'] | extend status_human_readable = case( status_int == 200, 'OK', status_int == 201, 'Created', status_int == 301, 'Moved Permanently', status_int == 500, 'Internal Server Error', 'Other' ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20extend%20status_code%20%3D%20case\(status_int%20%3D%3D%20200%2C%20'OK'%2C%20status_int%20%3D%3D%20201%2C%20'Created'%2C%20status_int%20%3D%3D%20301%2C%20'Moved%20Permanently'%2C%20status_int%20%3D%3D%20500%2C%20'Internal%20Server%20Error'%2C%20'Other'\)%22%7D) ## iff() Evaluates the first argument (the predicate), and returns the value of either the second or third arguments. The second and third arguments must be of the same type. ### Arguments * predicate: An expression that evaluates to a boolean value. * ifTrue: An expression that gets evaluated and its value returned from the function if predicate evaluates to `true`. * ifFalse: An expression that gets evaluated and its value returned from the function if predicate evaluates to `false`. ### Returns This function returns the value of ifTrue if predicate evaluates to true, or the value of ifFalse otherwise. ### Examples ```kusto iff(predicate, ifTrue, ifFalse) ``` ```kusto ['sample-http-logs'] | project Status = iff(req_duration_ms == 1, "numeric", "Inactive") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20Status%20%3D%20iff%28req_duration_ms%20%3D%3D%201%2C%20%5C%22numeric%5C%22%2C%20%5C%22Inactive%5C%22%29%22%7D) # Conversion functions Learn how to use and combine different conversion functions in APL ## Conversion functions | **Function Name** | **Description** | | --------------------------------------------- | ------------------------------------------------------------------------------------------ | | [ensure\_field()](#ensure-field) | Ensures the existence of a field and returns its value or a typed nil if it doesn’t exist. | | [tobool()](#tobool) | Converts input to boolean (signed 8-bit) representation. | | [todatetime()](#todatetime) | Converts input to datetime scalar. | | [todouble(), toreal()](#todouble\(\),-toreal) | Converts the input to a value of type `real`. `todouble()` and `toreal()` are synonyms. | | [tostring()](#tostring) | Converts input to a string representation. | | [totimespan()](#totimespan) | Converts input to timespan scalar. | | [tohex()](#tohex) | Converts input to a hexadecimal string. | | [tolong()](#tolong) | Converts input to long (signed 64-bit) number representation. | | [dynamic\_to\_json()](#dynamic-to-json) | Converts a scalar value of type dynamic to a canonical string representation. | | [isbool()](#isbool) | Returns a value of true or false if the expression value is passed. | | [toint()](#toint) | Converts the input to an integer value (signed 64-bit) number representation. | ## ensure\_field() Ensures the existence of a field and returns its value or a typed nil if it doesn’t exist. ### Arguments | **name** | **type** | **description** | | ----------- | -------- | ------------------------------------------------------------------------------------------------------ | | field\_name | string | The name of the field to ensure exists. | | field\_type | type | The type of the field. See [scalar data types](/apl/data-types/scalar-data-types) for supported types. | ### Returns This function returns the value of the specified field if it exists, otherwise it returns a typed nil. ### Examples ```kusto ensure_field(field_name, field_type) ``` ### Handle missing fields In this example, the value of `show_field` is nil because the `myfield` field doesn’t exist. ```kusto ['sample-http-logs'] | extend show_field = ensure_field("myfield", typeof(string)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20show_field%20%3D%20ensure_field%28%27myfield%27%2C%20typeof%28string%29%29%22%7D) ### Access existing fields In this example, the value of `newstatus` is the value of `status` because the `status` field exists. ```kusto ['sample-http-logs'] | extend newstatus = ensure_field("status", typeof(string)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20newstatus%20%3D%20ensure_field%28%27status%27%2C%20typeof%28string%29%29%22%7D) ### Future-proof queries In this example, the query is prepared for a field named `upcoming_field` that is expected to be added to the data soon. By using `ensure_field()`, logic can be written around this future field, and the query will work when the field becomes available. ```kusto ['sample-http-logs'] | extend new_field = ensure_field("upcoming_field", typeof(int)) | where new_field > 100 ``` ## tobool() Converts input to boolean (signed 8-bit) representation. ### Arguments * Expr: Expression that will be converted to boolean. ### Returns * If conversion is successful, result will be a boolean. If conversion isn’t successful, result will be `false` ### Examples ```kusto tobool(Expr) toboolean(Expr) (alias) ``` ```kusto tobool("true") == true ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20tobool%28%5C%22true%5C%22%29%20%3D%3D%20true%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": true } ``` ## todatetime() Converts input to datetime scalar. ### Arguments * Expr: Expression that will be converted to datetime. ### Returns If the conversion is successful, the result will be a datetime value. Else, the result will be `false.` ### Examples ```kusto todatetime(Expr) ``` ```kusto todatetime("2022-11-13") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20todatetime%28%5C%222022-11-13%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "boo": "2022-11-13T00:00:00Z" } ``` ## todouble(), toreal() Converts the input to a value of type real. **(todouble() is an alternative word to toreal())** ### Arguments * Expr: An expression whose value will be converted to a value of type `real.` ### Returns If conversion is successful, the result is a value of type real. If conversion is not successful, the result returns false. ### Examples ```kusto toreal(Expr)todouble(Expr) ``` ```kusto toreal("1567") == 1567 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20toreal%28%5C%221567%5C%22%29%20%3D%3D%201567%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": true } ``` ## tostring() Converts input to a string representation. ### Arguments * `Expr:` Expression that will be converted to string. ### Returns If the Expression value is non-null, the result will be a string representation of the Expression. If the Expression value is null, the result will be an empty string. ### Examples ```kusto tostring(Expr) ``` ```kusto tostring(axiom) == "axiom" ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20tostring%28%5C%22axiom%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": "axiom" } ``` ## totimespan Converts input to timespan scalar. ### Arguments * `Expr:` Expression that will be converted to timespan. ### Returns If conversion is successful, result will be a timespan value. Else, result will be false. ### Examples ```kusto totimespan(Expr) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20totimespan%282022-11-13%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "conversion_function": "1.998µs" } ``` ## tohex() Converts input to a hexadecimal string. ### Arguments * Expr: int or long value that will be converted to a hex string. Other types are not supported. ### Returns If conversion is successful, result will be a string value. If conversion is not successful, result will be false. ### Examples ```kusto tohex(value) ``` ```kusto tohex(-546) == 'fffffffffffffdde' ``` ```kusto tohex(546) == '222' ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20tohex%28-546%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": "fffffffffffffdde" } ``` ## tolong() Converts input to long (signed 64-bit) number representation. ### Arguments * Expr: Expression that will be converted to long. ### Returns If conversion is successful, result will be a long number. If conversion is not successful, result will be false. ### Examples ```kusto tolong(Expr) ``` ```kusto tolong("241") == 241 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20tolong%28%5C%22241%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": 241 } ``` ## dynamic\_to\_json() Converts a scalar value of type `dynamic` to a canonical `string` representation. ### Arguments * dynamic input (EXpr): The function accepts one argument. ### Returns Returns a canonical representation of the input as a value of type `string`, according to the following rules: * If the input is a scalar value of type other than `dynamic`, the output is the app of `tostring()` to that value. * If the input in an array of values, the output is composed of the characters **\[, ,, and ]** interspersed with the canonical representation described here of each array element. * If the input is a property bag, the output is composed of the characters **\{, ,, and }** interspersed with the colon (:)-delimited name/value pairs of the properties. The pairs are sorted by the names, and the values are in the canonical representation described here of each array element. ### Examples ```kusto dynamic_to_json(dynamic) ``` ```kusto ['sample-http-logs'] | project conversion_function = dynamic_to_json(dynamic([1,2,3])) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20dynamic_to_json%28dynamic%28%5B1%2C2%2C3%5D%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": "[1,2,3]" } ``` ## isbool() Returns a value of true or false if the expression value is passed. ### Arguments * Expr: The function accepts one argument. The variable of expression to be evaluated. ### Returns Returns `true` if expression value is a bool, `false` otherwise. ### Examples ```kusto isbool(expression) ``` ```kusto isbool("pow") == false ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20conversion_function%20%3D%20isbool%28%5C%22pow%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "conversion_function": false } ``` *** ## toint() Converts the input to an integer value (signed 64-bit) number representation. ### Arguments * Value: The value to convert to an [integer](/apl/data-types/scalar-data-types#the-int-data-type). ### Returns If the conversion is successful, the result will be an integer. Otherwise, the result will be `null`. ### Examples ```kusto toint(value) ``` ```kusto | project toint("456") == 456 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20toint%28%5C%22456%5C%22%29%20%3D%3D%20456%22%7D) # Datetime functions Learn how to use and combine different timespan functions in APL ## DateTime/ Timespan functions | **Function Name** | **Description** | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | [ago()](#ago) | Subtracts the given timespan from the current UTC clock time. | | [datetime\_add()](#datetime-add) | Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime. | | [datetime\_part()](#datetime-part) | Extracts the requested date part as an integer value. | | [datetime\_diff()](#datetime-diff) | Calculates calendarian difference between two datetime values. | | [dayofmonth()](#dayofmonth) | Returns the integer number representing the day number of the given month | | [dayofweek()](#dayofweek) | Returns the integer number of days since the preceding Sunday, as a timespan. | | [dayofyear()](#dayofyear) | Returns the integer number represents the day number of the given year. | | [endofyear()](#endofyear) | Returns the end of the year containing the date | | [getmonth()](#getmonth) | Get the month number (1-12) from a datetime. | | [getyear()](#getyear) | Returns the year part of the `datetime` argument. | | [hourofday()](#hourofday) | Returns the integer number representing the hour number of the given date | | [endofday()](#endofday) | Returns the end of the day containing the date | | [now()](#now) | Returns the current UTC clock time, optionally offset by a given timespan. | | [endofmonth()](#endofmonth) | Returns the end of the month containing the date | | [endofweek()](#endofweek) | Returns the end of the week containing the date. | | [monthofyear()](#monthofyear) | Returns the integer number represents the month number of the given year. | | [startofday()](#startofday) | Returns the start of the day containing the date | | [startofmonth()](#startofmonth) | Returns the start of the month containing the date | | [startofweek()](#startofweek) | Returns the start of the week containing the date | | [startofyear()](#startofyear) | Returns the start of the year containing the date | * We support the ISO 8601 format, which is the standard format for representing dates and times in the Gregorian calendar. [Check them out here](/apl/data-types/scalar-data-types#supported-formats) ## ago() Subtracts the given timespan from the current UTC clock time. ### Arguments * Interval to subtract from the current UTC clock time ### Returns now() - a\_timespan ### Example ```kusto ago(6h) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20date_time_functions%20%3D%20ago%286h%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "date_time_functions": "2023-09-11T20:12:39Z" } ``` ```kusto ago(3d) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20date_time_functions%20%3D%20ago%283d%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "date_time_functions": "2023-09-09T02:13:29Z" } ``` ## datetime\_add() Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime. ### Arguments * period: string. * amount: integer. * datetime: datetime value. ### Returns A date after a certain time/date interval has been added. ### Example ```kusto datetime_add(period,amount,datetime) ``` ```kusto ['sample-http-logs'] | project new_datetime = datetime_add( "month", 1, datetime(2016-10-06)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_add%28%20%5C%22month%5C%22%2C%201%2C%20datetime%282016-10-06%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "new_datetime": "2016-11-06T00:00:00Z" } ``` ## datetime\_part() Extracts the requested date part as an integer value. ### Arguments * date: datetime * part: string ### Returns An integer representing the extracted part. ### Examples ```kusto datetime_part(part,datetime) ``` ```kusto ['sample-http-logs'] | project new_datetime = datetime_part("Day", datetime(2016-06-26T08:20:03.123456Z)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_part%28%5C%22Day%5C%22%2C%20datetime%282016-06-26T08%3A20%3A03.123456Z%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "new_datetime": 26 } ``` ## datetime\_diff() Calculates calendarian difference between two datetime values. ### Arguments * period: string. * datetime\_1: datetime value. * datetime\_2: datetime value. ### Returns An integer, which represents amount of periods in the result of subtraction (datetime\_1 - datetime\_2). ### Example ```kusto datetime_diff(period,datetime_1,datetime_2) ``` ```kusto ['sample-http-logs'] | project new_datetime = datetime_diff("week", datetime(2019-06-26T08:20:03.123456Z), datetime(2014-06-26T08:19:03.123456Z)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_diff%28%5C%22week%5C%22%2C%20datetime%28%5C%222019-06-26T08%3A20%3A03.123456Z%5C%22%29%2C%20datetime%28%5C%222014-06-26T08%3A19%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "new_datetime": 260 } ``` ```kusto ['sample-http-logs'] | project new_datetime = datetime_diff("week", datetime(2015-11-08), datetime(2014-11-08)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_diff%28%5C%22week%5C%22%2C%20datetime%28%5C%222014-11-08%5C%22%29%2C%20datetime%28%5C%222014-11-08%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "new_datetime": 52 } ``` ## dayofmonth() Returns the integer number representing the day number of the given month ### Arguments * `a_date`: A `datetime` ### Returns day number of the given month. ### Example ```kusto dayofmonth(a_date) ``` ```kusto ['sample-http-logs'] | project day_of_the_month = dayofmonth(datetime(2017-11-30)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_month%20%3D%20dayofmonth%28datetime%28%5C%222017-11-30%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "day_of_the_month": 30 } ``` ## dayofweek() Returns the integer number of days since the preceding Sunday, as a timespan. ### Arguments * a\_date: A datetime. ### Returns The `timespan` since midnight at the beginning of the preceding Sunday, rounded down to an integer number of days. ### Example ```kusto dayofweek(a_date) ``` ```kusto ['sample-http-logs'] | project day_of_the_week = dayofweek(datetime(2019-05-18)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_week%20%3D%20dayofweek%28datetime%28%5C%222019-05-18%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "day_of_the_week": 6 } ``` ## dayofyear() Returns the integer number represents the day number of the given year. ### Arguments * `a_date`: A `datetime.` ### Returns `day number` of the given year. ### Example ```kusto dayofyear(a_date) ``` ```kusto ['sample-http-logs'] | project day_of_the_year = dayofyear(datetime(2020-07-20)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_year%20%3D%20dayofyear%28datetime%28%5C%222020-07-20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "day_of_the_year": 202 } ``` ## endofyear() Returns the end of the year containing the date ### Arguments * date: The input date. ### Returns A datetime representing the end of the year for the given date value ### Example ```kusto endofyear(date) ``` ```kusto ['sample-http-logs'] | extend end_of_the_year = endofyear(datetime(2016-06-26T08:20)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20%20end_of_the_year%20%3D%20endofyear%28datetime%28%5C%222016-06-26T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "end_of_the_year": "2016-12-31T23:59:59.999999999Z" } ``` ## getmonth() Get the month number (1-12) from a datetime. ```kusto ['sample-http-logs'] | extend get_specific_month = getmonth(datetime(2020-07-26T08:20)) ``` ## getyear() Returns the year part of the `datetime` argument. ### Example ```kusto getyear(datetime()) ``` ```kusto ['sample-http-logs'] | project get_specific_year = getyear(datetime(2020-07-26)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20get_specific_year%20%3D%20getyear%28datetime%28%5C%222020-07-26%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "get_specific_year": 2020 } ``` ## hourofday() Returns the integer number representing the hour number of the given date ### Arguments * a\_date: A datetime. ### Returns hour number of the day (0-23). ### Example ```kusto hourofday(a_date) ``` ```kusto ['sample-http-logs'] | project get_specific_hour = hourofday(datetime(2016-06-26T08:20:03.123456Z)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20get_specific_hour%20%3D%20hourofday%28datetime%28%5C%222016-06-26T08%3A20%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "get_specific_hour": 8 } ``` ## endofday() Returns the end of the day containing the date ### Arguments * date: The input date. ### Returns A datetime representing the end of the day for the given date value. ### Example ```kusto endofday(date) ``` ```kusto ['sample-http-logs'] | project end_of_day_series = endofday(datetime(2016-06-26T08:20:03.123456Z)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_day_series%20%3D%20endofday%28datetime%28%5C%222016-06-26T08%3A20%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "end_of_day_series": "2016-06-26T23:59:59.999999999Z" } ``` ## now() Returns the current UTC clock time, optionally offset by a given timespan. This function can be used multiple times in a statement and the clock time being referenced will be the same for all instances. ### Arguments * offset: A timespan, added to the current UTC clock time. Default: 0. ### Returns The current UTC clock time as a datetime. ### Example ```kusto now([offset]) ``` ```kusto ['sample-http-logs'] | project returns_clock_time = now(-5d) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20returns_clock_time%20%3D%20now%28-5d%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "returns_clock_time": "2023-09-07T02:54:50Z" } ``` ## endofmonth() Returns the end of the month containing the date ### Arguments * date: The input date. ### Returns A datetime representing the end of the month for the given date value. ### Example ```kusto endofmonth(date) ``` ```kusto ['sample-http-logs'] | project end_of_the_month = endofmonth(datetime(2016-06-26T08:20)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_the_month%20%3D%20endofmonth%28datetime%28%5C%222016-06-26T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "end_of_the_month": "2016-06-30T23:59:59.999999999Z" } ``` ## endofweek() Returns the end of the week containing the date ### Arguments * date: The input date. ### Returns A datetime representing the end of the week for the given date value ### Example ```kusto endofweek(date) ``` ```kusto ['sample-http-logs'] | project end_of_the_week = endofweek(datetime(2019-04-18T08:20)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_the_week%20%3D%20endofweek%28datetime%28%5C%222019-04-18T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "end_of_the_week": "2019-04-20T23:59:59.999999999Z" } ``` ## monthofyear() Returns the integer number represents the month number of the given year. ### Arguments * `date`: A datetime. ### Returns month number of the given year. ### Example ```kusto monthofyear(datetime("2018-11-21")) ``` ```kusto ['sample-http-logs'] | project month_of_the_year = monthofyear(datetime(2018-11-11)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20month_of_the_year%20%3D%20monthofyear%28datetime%28%5C%222018-11-11%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "month_of_the_year": 11 } ``` ## startofday() Returns the start of the day containing the date ### Arguments * date: The input date. ### Returns A datetime representing the start of the day for the given date value ### Examples ```kusto startofday(datetime(2020-08-31)) ``` ```kusto ['sample-http-logs'] | project start_of_the_day = startofday(datetime(2018-11-11)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20start_of_the_day%20%3D%20startofday%28datetime%28%5C%222018-11-11%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "start_of_the_day": "2018-11-11T00:00:00Z" } ``` ## startofmonth() Returns the start of the month containing the date ### Arguments * date: The input date. ### Returns A datetime representing the start of the month for the given date value ### Example ```kusto ['github-issues-event'] | project start_of_the_month = startofmonth(datetime(2020-08-01)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20start_of_the_month%20%3D%20%20startofmonth%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "start_of_the_month": "2020-08-01T00:00:00Z" } ``` ```kusto ['hackernews'] | extend start_of_the_month = startofmonth(datetime(2020-08-01)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20project%20start_of_the_month%20%3D%20startofmonth%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "start_of_the_month": "2020-08-01T00:00:00Z" } ``` ## startofweek() Returns the start of the week containing the date Start of the week is considered to be a Sunday. ### Arguments * date: The input date. ### Returns A datetime representing the start of the week for the given date value ### Examples ```kusto ['github-issues-event'] | extend start_of_the_week = startofweek(datetime(2020-08-01)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20start_of_the_week%20%3D%20%20startofweek%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "start_of_the_week": "2020-07-26T00:00:00Z" } ``` ```kusto ['hackernews'] | extend start_of_the_week = startofweek(datetime(2020-08-01)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20project%20start_of_the_week%20%3D%20startofweek%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "start_of_the_week": "2020-07-26T00:00:00Z" } ``` ```kusto ['sample-http-logs'] | extend start_of_the_week = startofweek(datetime(2018-06-11T00:00:00Z)) ``` ## startofyear() Returns the start of the year containing the date ### Arguments * date: The input date. ### Returns A datetime representing the start of the year for the given date value ### Examples ```kusto ['sample-http-logs'] | project yearStart = startofyear(datetime(2019-04-03)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20yearStart%20%3D%20startofyear%28datetime%28%5C%222019-04-03%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "yearStart": "2019-01-01T00:00:00Z" } ``` ```kusto ['sample-http-logs'] | project yearStart = startofyear(datetime(2019-10-09 01:00:00.0000000)) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20yearStart%20%3D%20startofyear%28datetime%28%5C%222019-10-09%2001%3A00%3A00.0000000%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result: ```json { "yearStart": "2019-01-01T00:00:00Z" } ``` # Hash functions Learn how to use and combine various hash functions in APL ## Hash functions | **Function Name** | **Description** | | ------------------------------ | ------------------------------------------------ | | [hash\_md5()](#hash-md5) | Returns a MD5 hash value for the input value. | | [hash\_sha1()](#hash-sha1) | Returns a sha1 hash value for the input value. | | [hash\_sha256()](#hash-sha256) | Returns a SHA256 hash value for the input value. | | [hash\_sha512()](#hash-sha512) | Returns a SHA512 hash value for the input value. | ## hash\_md5() Returns an MD5 hash value for the input value. ### Arguments * source: The value to be hashed. ### Returns The MD5 hash value of the given scalar, encoded as a hex string (a string of characters, each two of which represent a single Hex number between 0 and 255). ### Examples ```kusto hash_md5(source) ``` ```kusto ['sample-http-logs'] | project md5_hash_value = hash_md5(content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20md5_hash_value%20%3D%20hash_md5%28content_type%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "md5_hash_value": "b980a9c041dbd33d5893fad65d33284b" } ``` ## hash\_sha1() Returns a SHA1 hash value for the input value. ### Arguments * source: The value to be hashed. ### Returns The sha1 hash value of the given scalar, encoded as a hex string ### Examples ```kusto hash_sha1(source) ``` ```kusto ['sample-http-logs'] | project sha1_hash_value = hash_sha1(content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20sha1_hash_value%20%3D%20hash_sha1%28content_type%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "sha1_hash_value": "9f9af029585ba014e07cd3910ca976cf56160616" } ``` ## hash\_sha256() Returns a SHA256 hash value for the input value. ### Arguments * source: The value to be hashed. ### Returns The sha256 hash value of the given scalar, encoded as a hex string (a string of characters, each two of which represent a single Hex number between 0 and 255). ### Examples ```kusto hash_sha256(source) ``` ```kusto ['sample-http-logs'] | project sha256_hash_value = hash_sha256(content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20sha256_hash_value%20%3D%20hash_sha256%28content_type%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "sha256_hash_value": "bb4770ff4ac5b7d2be41a088cb27d8bcaad53b574b6f27941e8e48e9e10fc25a" } ``` ## hash\_sha512() Returns a SHA512 hash value for the input value. ### Arguments * source: The value to be hashed. ### Returns The sha512 hash value of the given scalar, encoded as a hex string (a string of characters, each two of which represent a single Hex number between 0 and 511). ### Examples ```kusto hash_sha512(source) ``` ```kusto ['sample-http-logs'] | project sha512_hash_value = hash_sha512(status) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20sha512_hash_value%20%3D%20hash_sha512%28status%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "sha512_hash_value": "0878a61b503dd5a9fe9ea3545d6d3bd41c3b50a47f3594cb8bbab3e47558d68fc8fcc409cd0831e91afc4e609ef9da84e0696c50354ad86b25f2609efef6a834" } ``` *** ```kusto ['sample-http-logs'] | project sha512_hash_value = hash_sha512(content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20sha512_hash_value%20%3D%20hash_sha512%28content_type%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "sha512_hash_value": "95c6eacdd41170b129c3c287cfe088d4fafea34e371422b94eb78b9653a89d4132af33ef39dd6b3d80e18c33b21ae167ec9e9c2d820860689c647ffb725498c4" } ``` # IP functions Learn how to use and combine different ip functions in APL ## IP functions | **Function Name** | **Description** | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [format\_ipv4()](#format-ipv4) | Parses input with a netmask and returns string representing IPv4 address. | | [parse\_ipv4()](#parse-ipv4) | Converts input to long (signed 64-bit) number representation. | | [parse\_ipv4\_mask()](#parse-ipv4-mask) | Converts input string and IP-prefix mask to long (signed 64-bit) number representation. | | [ipv4\_is\_in\_range()](#ipv4-is-in-range) | Checks if IPv4 string address is in IPv4-prefix notation range. | | [ipv4\_is\_private()](#ipv4-is-private) | Checks if IPv4 string address belongs to a set of private network IPs. | | [ipv4\_netmask\_suffix()](#ipv4-netmask-suffix) | Returns the value of the IPv4 netmask suffix from IPv4 string address. | | [geo\_info\_from\_ip\_address()](#geo-info-from-ip-address) | Extracts geographical, geolocation, and network information from IP addresses. It supports both IPv4 and IPv6 addresses. | ### IP-prefix notation IP addresses can be defined with `IP-prefix notation` using a slash (**/**) character. The IP address to the LEFT of the slash (**/**\*) is the base IP address. The number (1 to 32) to the RIGHT of the slash (**/**) is the number of contiguous 1 bit in the netmask. For example, `192.168.2.0/24` will have an associated net/subnetmask containing 24 contiguous bits or `255.255.255.0` in dotted decimal format. ## format\_ipv4() Parses input with a netmask and returns string representing IPv4 address. ### Arguments * Expr(IP): A string or number representation of the IPv4 address. ### Returns If conversion is successful, the result will be a string representing IPv4 address. If conversion isn’t successful, the result will be an empty string. ### Example ```kusto format_ipv4(ip) ``` ```kusto ['sample-http-logs'] | project str_ipv4 = format_ipv4("192.168.2.0") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20str_ipv4%20%3D%20format_ipv4%28%5C%22192.168.2.0%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "str_ipv4": "192.168.2.0" } ``` ## parse\_ipv4() Converts IPv4 string to long (signed 64-bit) number representation. ### Arguments * Expr: String expression representing IPv4 that will be converted to long. String may include net-mask using IP-prefix notation. ### Returns If conversion is successful, the result will be a long number. If conversion isn’t successful, the result will be `null.` ### Example ```kusto parse_ipv4(Expr) ``` ```kusto ['sample-http-logs'] | project parsed_ipv4 = parse_ipv4("192.168.2.0") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20parsed_ipv4%20%3D%20parse_ipv4%28%5C%22192.168.2.0%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "parsed_ipv4": 3232236032 } ``` ## parse\_ipv4\_mask() Converts the input string of IPv4 and netmask to long number representation (signed 64-bit). ### Arguments * `Expr:` A string representation of the IPv4 address that will be converted to long. * `PrefixMask:` An integer from 0 to 32 representing the number of most-significant bits that are taken into account. ### Returns If conversion is successful, the result will be a long number. If conversion isn’t successful, the result will be `null.` ### Example ```kusto parse_ipv4_mask(Expr, PrefixMask) ``` ```kusto ['sample-http-logs'] | project parsed_ipv4 = parse_ipv4_mask("192.5.1.4", 24) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20parsed_ipv4%20%3D%20parse_ipv4_mask%28%5C%22192.5.1.4%5C%22%2C%2024%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "parsed_ipv4": 3221553408 } ``` ## ipv4\_is\_in\_range() Checks if IPv4 string address is in IPv4-prefix notation range. ### Arguments * Ipv4Address: A string expression representing an IPv4 address. * Ipv4Range: A string expression representing an IPv4 range using [IP-prefix notation](/apl/scalar-functions/ip-functions#ip-prefix-notation). ### Returns * `true`: If the long representation of the first IPv4 string argument is in range of the second IPv4 string argument. * `false`: Otherwise. * `null`: If conversion for one of the two IPv4 strings wasn’t successful. ### Examples ```kusto ipv4_is_in_range('192.168.1.5', '192.168.1.2/24') ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20ipv4_range%20%3D%20ipv4_is_in_range%28'192.168.1.5'%2C%20'192.168.1.2%2F24'%29%22%7D) * Result ```json { "ipv4_in_range": true } ``` ```kusto ipv4_is_in_range("127.2.3.1", "127.2.3.1") == true ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20ipv4_range%20%3D%20ipv4_is_in_range%28%5C%22127.2.3.1%5C%22%2C%20%5C%22127.2.3.1%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "ipv4_range": true } ``` ```kusto ipv4_is_in_range('192.168.1.5', '192.168.1.5/24') == true ``` ```kusto ipv4_is_in_range('192.168.1.5', '192.168.2.1/24') == false ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%7Cproject%20ipv4_range%20%3D%20ipv4_is_in_range%28%27%20192.168.1.5%27%2C%20%27192.168.2.1%2F24%27%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "ipv4_range": false } ``` ## ipv4\_is\_private() Checks if IPv4 string address belongs to a set of private network IPs. ### Private IPv4 addresses The private IPv4 addresses reserved for private networks by the Internet Assigned Numbers Authority (IANA) are: | **IP address range** | **Number of addresses** | **Largest CIDR block (subnet mask)** | | --------------------------------- | ----------------------- | ------------------------------------ | | **10.0.0.0 – 10.255.255.255** | **16777216** | **10.0.0.0/8 (255.0.0.0)** | | **172.16.0.0 – 172.31.255.255** | **1048576** | **172.16.0.0/12 (255.240.0.0)** | | **192.168.0.0 – 192.168.255.255** | **65536** | **192.168.0.0/16 (255.255.0.0)** | ### Arguments * Expr: A string expression representing an IPv4 address. IPv4 strings can be masked using [IP-prefix notation.](/apl/scalar-functions/ip-functions#ip-prefix-notation) ### Returns * `true`: If the IPv4 address belongs to any of the private network ranges. * `false`: Otherwise. * `null`: If parsing of the input as IPv4 address string wasn’t successful. ### Example ```kusto ipv4_is_private('192.168.2.1') == true ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20ipv4_range%20%3D%20ipv4_is_private%28%27192.168.2.1%27%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "ipv4_private": true } ``` ```kusto ipv4_is_private('208.1.2.3') == false ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20ipv4_private%20%3D%20ipv4_is_private%28%27208.1.2.3%27%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "ipv4_private": false } ``` ## ipv4\_netmask\_suffix() Returns the value of the IPv4 netmask suffix from IPv4 string address. ### Arguments Expr: A string expression representing an IPv4 address. IPv4 strings can be masked using [IP-prefix notation](/apl/scalar-functions/ip-functions#ip-prefix-notation). ### Returns * The value of the netmask suffix the IPv4 address. If suffix is not present in the input, a value of **32** (full netmask suffix) is returned. * null: If parsing of the input as IPv4 address string wasn’t successful. ### Example ```kusto ipv4_netmask_suffix('192.164.2.2/24') == 24 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20netmask_suffix%20%3D%20ipv4_netmask_suffix%28%27192.164.2.2%2F24%27%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "netmask_suffix": 24 } ``` ```kusto ipv4_netmask_suffix('192.166.1.2') == 32 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20netmask_suffix%20%3D%20ipv4_netmask_suffix%28%27192.166.1.2%27%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D) * Result ```json { "netmask_suffix": 32 } ``` ## geo\_info\_from\_ip\_address() Extracts geographical, geolocation, and network information from IP addresses. It supports both IPv4 and IPv6 addresses. ### Arguments | Name | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------------- | | ipAddress | String | Yes | The IP address to extract information from. Can be IPv4 or IPv6 | ### Returns A dynamic object containing the information on the IP address’s whereabouts (if the information is available). The object contains the following fields: | Name | Type | Description | | ------------ | ------ | -------------------------------------------- | | country | string | Country name | | state | string | State (subdivision) name | | city | string | City name | | latitude | real | Latitude coordinate | | longitude | real | Longitude coordinate | | country\_iso | string | ISO code of the country | | time\_zone | string | Time zone in which the IP address is located | ### Examples ```kusto geo_info_from_ip_address(IpAddress) ``` ### IPv4 Examples ### Extracting geolocation information from IPv4 address ```kusto ['sample-http-logs'] | extend ip_location = geo_info_from_ip_address('172.217.11.4') ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20ip_location%20%3D%20geo_info_from_ip_address%28%27172.217.11.4%27%29%22%7D) ### Projecting geolocation information from IPv4 address ```kusto ['sample-http-logs'] | project ip_location=geo_info_from_ip_address('20.53.203.50') ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20ip_location%3Dgeo_info_from_ip_address%28%2720.53.203.50%27%29%22%7D) ### Filtering geolocation information from IPv4 address ```kusto ['sample-http-logs'] | extend ip_location = geo_info_from_ip_address('20.53.203.50') | where ip_location.country == "Australia" and ip_location.country_iso == "AU" and ip_location.state == "New South Wales" ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20ip_location%20%3D%20geo_info_from_ip_address%28%2720.53.203.50%27%29%5Cn%7C%20where%20ip_location.country%20%3D%3D%20%5C%22Australia%5C%22%20and%20ip_location.country_iso%20%3D%3D%20%5C%22AU%5C%22%20and%20ip_location.state%20%3D%3D%20%5C%22New%20South%20Wales%5C%22%22%7D) ### Grouping geolocation information from IPv4 address ```kusto ['sample-http-logs'] | extend ip_location = geo_info_from_ip_address('20.53.203.50') | summarize Count=count() by ip_location.state, ip_location.city, ip_location.latitude, ip_location.longitude ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20ip_location%20%3D%20geo_info_from_ip_address%28%2720.53.203.50%27%29%5Cn%7C%20summarize%20Count%3Dcount%28%29%20by%20ip_location.state%2C%20ip_location.city%2C%20ip_location.latitude%2C%20ip_location.longitude%22%7D) ### IPv6 Examples ### Extracting geolocation information from IPv6 address ```kusto ['sample-http-logs'] | extend ip_location = geo_info_from_ip_address('2607:f8b0:4005:805::200e') ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20ip_location%20%3D%20geo_info_from_ip_address%28%272607%3Af8b0%3A4005%3A805%3A%3A200e%27%29%22%7D) ### Projecting geolocation information from IPv6 address ```kusto ['sample-http-logs'] | project ip_location=geo_info_from_ip_address('2a03:2880:f12c:83:face:b00c::25de') ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20ip_location%3Dgeo_info_from_ip_address%28%272a03%3A2880%3Af12c%3A83%3Aface%3Ab00c%3A%3A25de%27%29%22%7D) ### Filtering geolocation information from IPv6 address ```kusto ['sample-http-logs'] | extend ip_location = geo_info_from_ip_address('2a03:2880:f12c:83:face:b00c::25de') | where ip_location.country == "United States" and ip_location.country_iso == "US" and ip_location.state == "Florida" ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20ip_location%20%3D%20geo_info_from_ip_address%28%272a03%3A2880%3Af12c%3A83%3Aface%3Ab00c%3A%3A25de%27%29%5Cn%7C%20where%20ip_location.country%20%3D%3D%20%5C%22United%20States%5C%22%20and%20ip_location.country_iso%20%3D%3D%20%5C%22US%5C%22%20and%20ip_location.state%20%3D%3D%20%5C%22Florida%5C%22%22%7D) ### Grouping geolocation information from IPv6 address ```kusto ['sample-http-logs'] | extend ip_location = geo_info_from_ip_address('2a03:2880:f12c:83:face:b00c::25de') | summarize Count=count() by ip_location.state, ip_location.city, ip_location.latitude, ip_location.longitude ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20ip_location%20%3D%20geo_info_from_ip_address%28%272a03%3A2880%3Af12c%3A83%3Aface%3Ab00c%3A%3A25de%27%29%5Cn%7C%20summarize%20Count%3Dcount%28%29%20by%20ip_location.state%2C%20ip_location.city%2C%20ip_location.latitude%2C%20ip_location.longitude%22%7D) # Mathematical functions Learn how to use and combine different mathematical functions in APL ## Mathematical functions | **Function Name** | **Description** | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | [abs()](#abs) | Calculates the absolute value of the input. | | [acos()](#acos) | Returns the angle whose cosine is the specified number (the inverse operation of cos()). | | [asin()](#asin) | Returns the angle whose sine is the specified number (the inverse operation of sin()). | | [atan()](#atan) | Returns the angle whose tangent is the specified number (the inverse operation of tan()). | | [atan2()](#atan2) | Calculates the angle, in radians, between the positive x-axis and the ray from the origin to the point (y, x). | | [cos()](#cos) | Returns the cosine function. | | [degrees()](#degrees) | Converts angle value in radians into value in degrees, using formula degrees = (180 / PI) \* angle-in-radians. | | [exp()](#exp) | The base-e exponential function of x, which is e raised to the power x: e^x. | | [exp2()](#exp2) | The base-2 exponential function of x, which is 2 raised to the power x: 2^x. | | [gamma()](#gamma) | Computes gamma function. | | [isinf()](#isinf) | Returns whether input is an infinite (positive or negative) value. | | [isnan()](#isnan) | Returns whether input is Not-a-Number (NaN) value. | | [log()](#log) | Returns the natural logarithm function. | | [log10()](#log10) | Returns the common (base-10) logarithm function. | | [log2()](#log2) | Returns the base-2 logarithm function. | | [loggamma()](#loggamma) | Computes log of absolute value of the gamma function. | | [not()](#not) | Reverses the value of its bool argument. | | [pi()](#pi) | Returns the constant value of Pi (π). | | [pow()](#pow) | Returns a result of raising to power. | | [radians()](#radians) | Converts angle value in degrees into value in radians, using formula radians = (PI / 180) \* angle-in-degrees. | | [round()](#round) | Returns the rounded source to the specified precision. | | [sign()](#sign) | Sign of a numeric expression. | | [sin()](#sin) | Returns the sine function. | | [sqrt()](#sqrt) | Returns the square root function. | | [tan()](#tan) | Returns the tangent function. | | [exp10()](#exp10) | The base-10 exponential function of x, which is 10 raised to the power x: 10^x. | | [isint()](#isint) | Returns whether input is an integer (positive or negative) value | | [isfinite()](#isfinite) | Returns whether input is a finite value (is neither infinite nor NaN). | ## abs() Calculates the absolute value of the input. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | --------------------- | ------------------------ | -------------------------- | | x | int, real or timespan | Required | The value to make absolute | ### Returns * Absolute value of x. ### Examples ```kusto abs(x) ``` ```kusto abs(80.5) == 80.5 ``` ```kusto ['sample-http-logs'] | project absolute_value = abs(req_duration_ms) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20absolute_value%20%3D%20abs%28req_duration_ms%29%22%7D) ## acos() Returns the angle whose cosine is the specified number (the inverse operation of cos()) . ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | -------------------------------- | | x | real | Required | A real number in range \[-1,. 1] | ### Returns * The value of the arc cosine of x * `null` if `x` \< -1 or `x` > 1 ### Examples ```kusto acos(x) ``` ```kusto acos(-1) == 3.141592653589793 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20cosine_angle%20%3D%20acos%28-1%29%22%7D) ## asin() Returns the angle whose sine is the specified number (the inverse operation of sin()) . ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | -------------------------------- | | x | real | Required | A real number in range \[-1,. 1] | * x: A real number in range \[-1, 1]. ### Returns * The value of the arc sine of x * null if x \< -1 or x > 1 ### Examples ```kusto asin(x) ``` ```kusto ['sample-http-logs'] | project inverse_sin_angle = asin(-1) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20inverse_sin_angle%20%3D%20asin%28-1%29%22%7D) ## atan() Returns the angle whose tangent is the specified number (the inverse operation of tan()) . ### Arguments x: A real number. ### Returns The value of the arc tangent of x ### Examples ```kusto atan(x) ``` ```kusto atan(-1) == -0.7853981633974483 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20inverse_tan_angle%20%3D%20atan%28-1%29%22%7D) ## atan2() Calculates the angle, in radians, between the positive x-axis and the ray from the origin to the point (y, x). ### Arguments x: X coordinate (a real number). y: Y coordinate (a real number). ### Returns The angle, in radians, between the positive x-axis and the ray from the origin to the point (y, x). ### Examples ```kusto atan2(y,x) ``` ```kusto atan2(-1, 1) == -0.7853981633974483 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20angle_in_rads%20%3D%20atan2%28-1%2C%201%29%22%7D) ## cos() Returns the cosine function. ### Arguments x: A real number. ### Returns The result of cos(x) ### Examples ```kusto cos(x) ``` ```kusto cos(-1) == 0.5403023058681398 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20cosine_function%20%3D%20cos%28-1%29%22%7D) ## degrees() Converts angle value in radians into value in degrees, using formula degrees = (180 / PI ) \* angle\_in\_radians ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ----------------- | | a | real | Required | Angle in radians. | ### Returns The corresponding angle in degrees for an angle specified in radians. ### Examples ```kusto degrees(a) ``` ```kusto degrees(3.14) == 179.9087476710785 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20degree_rads%20%3D%20degrees%283.14%29%22%7D) ## exp() The base-e exponential function of x, which is e raised to the power x: e^x. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | ----------- | ------------------------ | ---------------------- | | x | real number | Required | Value of the exponent. | ### Returns * Exponential value of x. * For natural (base-e) logarithms, see [log()](/apl/scalar-functions/mathematical-functions#log\(\)). * For exponential functions of base-2 and base-10 logarithms, see [exp2()](/apl/scalar-functions/mathematical-functions#exp2\(\)), [exp10()](/apl/scalar-functions/mathematical-functions#exp10\(\)) ### Examples ```kusto exp(x) ``` ```kusto exp(1) == 2.718281828459045 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20exponential_value%20%3D%20exp%281%29%22%7D) ## exp2() The base-2 exponential function of x, which is 2 raised to the power x: 2^x. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | ----------- | ------------------------ | ---------------------- | | x | real number | Required | Value of the exponent. | ### Returns * Exponential value of x. * For natural (base-2) logarithms, see [log2()](/apl/scalar-functions/mathematical-functions#log2\(\)). * For exponential functions of base-e and base-10 logarithms, see [exp()](/apl/scalar-functions/mathematical-functions#exp\(\)), [exp10()](/apl/scalar-functions/mathematical-functions#exp10\(\)) ### Examples ```kusto exp2(x) ``` ```kusto | project base_2_exponential_value = exp2(req_duration_ms) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20base_2_exponential_value%20%3D%20exp2%28req_duration_ms%29%22%7D) ## gamma() Computes [gamma function](https://en.wikipedia.org/wiki/Gamma_function) ### Arguments * x: Parameter for the gamma function ### Returns * Gamma function of x. * For computing log-gamma function, see loggamma(). ### Examples ```kusto gamma(x) ``` ```kusto gamma(4) == 6 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20gamma_function%20%3D%20gamma%284%29%22%7D) ## isinf() Returns whether input is an infinite (positive or negative) value. ### Example ```kusto isinf(x) ``` ```kusto isinf(45.56) == false ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20infinite_value%20%3D%20isinf%2845.56%29%22%7D) ### Arguments x: A real number. ### Returns A non-zero value (true) if x is a positive or negative infinite; and zero (false) otherwise. ## isnan() Returns whether input is Not-a-Number (NaN) value. ### Arguments x: A real number. ### Returns A non-zero value (true) if x is NaN; and zero (false) otherwise. ### Examples ```kusto isnan(x) ``` ```kusto isnan(45.56) == false ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20nan%20%3D%20isnan%2845.56%29%22%7D) ## log() log() returns the natural logarithm function. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------ | | x | real | Required | A real number > 0. | ### Returns The natural logarithm is the base-e logarithm: the inverse of the natural exponential function (exp). null if the argument is negative or null or can’t be converted to a real value. ### Examples ```kusto log(x) ``` ```kusto log(1) == 0 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20natural_log%20%3D%20log%281%29%22%7D) ## log10() log10() returns the common (base-10) logarithm function. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------ | | x | real | Required | A real number > 0. | ### Returns The common logarithm is the base-10 logarithm: the inverse of the exponential function (exp) with base 10. null if the argument is negative or null or can’t be converted to a real value. ### Examples ```kusto log10(x) ``` ```kusto log10(4) == 0.6020599913279624 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20base10%20%3D%20log10%284%29%22%7D) ## log2() log2() returns the base-2 logarithm function. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------ | | x | real | Required | A real number > 0. | ### Returns The logarithm is the base-2 logarithm: the inverse of the exponential function (exp) with base 2. null if the argument is negative or null or can’t be converted to a real value. ### Examples ```kusto log2(x) ``` ```kusto log2(6) == 2.584962500721156 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20base2_log%20%3D%20log2%286%29%22%7D) ## loggamma() Computes log of absolute value of the [gamma function](https://en.wikipedia.org/wiki/Gamma_function) ### Arguments x: Parameter for the gamma function ### Returns * Returns the natural logarithm of the absolute value of the gamma function of x. ### Examples ````kusto loggamma(x) ```kusto loggamma(16) == 27.89927138384089 ```` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20gamma_function%20%3D%20loggamma%2816%29%22%7D) ## not() Reverses the value of its bool argument. ### Examples ```kusto not(expr) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20reverse%20%3D%20not%28false%29%22%7D) ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ----------------------------------- | | Expr | bool | Required | A `bool` expression to be reversed. | ### Returns Returns the reversed logical value of its bool argument. ## pi() Returns the constant value of Pi. ### Returns * The double value of Pi (3.1415926...) ### Examples ```kusto pi() ``` ```kusto ['sample-http-logs'] | project pie = pi() ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20pie%20%3D%20pi%28%29%22%7D) ## pow() Returns a result of raising to power ### Examples ```kusto pow(base, exponent ) ``` ```kusto pow(2, 6) == 64 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20power%20%3D%20pow%282%2C%206%29%22%7D) ### Arguments * *base:* Base value. * *exponent:* Exponent value. ### Returns Returns base raised to the power exponent: base ^ exponent. ## radians() Converts angle value in degrees into value in radians, using formula `radians = (PI / 180 ) * angle_in_degrees` ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | --------------------------------- | | a | real | Required | Angle in degrees (a real number). | ### Returns The corresponding angle in radians for an angle specified in degrees. ### Examples ```kusto radians(a) ``` ```kusto radians(60) == 1.0471975511965976 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20radians%20%3D%20radians%2860%29%22%7D) ## round() Returns the rounded source to the specified precision. ### Arguments * source: The source scalar the round is calculated on. * Precision: Number of digits the source will be rounded to.(default value is 0) ### Returns The rounded source to the specified precision. ### Examples ```kusto round(source [, Precision]) ``` ```kusto round(25.563663) == 26 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20rounded_value%20%3D%20round%2825.563663%29%22%7D) ## sign() Sign of a numeric expression ### Examples ```kusto sign(x) ``` ```kusto sign(25.563663) == 1 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20numeric_expression%20%3D%20sign%2825.563663%29%22%7D) ### Arguments * x: A real number. ### Returns * The positive (+1), zero (0), or negative (-1) sign of the specified expression. ## sin() Returns the sine function. ### Examples ```kusto sin(x) ``` ```kusto sin(25.563663) == 0.41770848373492825 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20sine_function%20%3D%20sin%2825.563663%29%22%7D) ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | --------------- | | x | real | Required | A real number. | ### Returns The result of sin(x) ## sqrt() Returns the square root function. ### Examples ```kusto sqrt(x) ``` ```kusto sqrt(25.563663) == 5.0560521160288685 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20squareroot%20%3D%20sqrt%2825.563663%29%22%7D) ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------- | | x | real | Required | A real number >= 0. | ### Returns * A positive number such that \_sqrt(x) \_ sqrt(x) == x\* * null if the argument is negative or cannot be converted to a real value. ## tan() Returns the tangent function. ### Examples ```kusto tan(x) ``` ```kusto tan(25.563663) == 0.4597371460602336 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20tangent_function%20%3D%20tan%2825.563663%29%22%7D) ### Argument | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | --------------- | | x | real | Required | A real number. | ### Returns * The result of `tan(x)` ## exp10() The base-10 exponential function of x, which is 10 raised to the power x: 10^x. ### Examples ```kusto exp10(x) ``` ```kusto exp10(25.563663) == 36,615,333,994,520,800,000,000,000 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20base_10_exponential%20%3D%20pow%2810%2C%2025.563663%29%22%7D) ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------------------------- | | x | real | Required | A real number, value of the exponent. | ### Returns * Exponential value of x. * For natural (base-10) logarithms, see [log10()](/apl/scalar-functions/mathematical-functions#log10\(\)). * For exponential functions of base-e and base-2 logarithms, see [exp()](/apl/scalar-functions/mathematical-functions#exp\(\)), [exp2()](/apl/scalar-functions/mathematical-functions#exp2\(\)) ## isint() Returns whether input is an integer (positive or negative) value. ### Arguments * Expr: expression value which can be a real number ### Returns A non-zero value (true) if expression is a positive or negative integer; and zero (false) otherwise. ### Examples ```kusto isint(expression) ``` ```kusto isint(resp_body_size_bytes) == true ``` ```kusto isint(25.563663) == false ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20integer_value%20%3D%20isint%2825.563663%29%22%7D) ## isfinite() Returns whether input is a finite value (is neither infinite nor NaN). ### Arguments * number: A real number. ### Returns A non-zero value (true) if x is finite; and zero (false) otherwise. ### Examples ```kusto isfinite(number) ``` ```kusto isfinite(25.563663) == true ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20isfinite_value%20%3D%20isfinite%2825.563663%29%22%7D) # Pair functions Learn how to use and combine different pair functions in APL ## Pair functions | **Function Name** | **Description** | | ---------------------------- | ------------------------------------ | | [pair()](#pair) | Creates a pair from a key and value. | | [parse\_pair()](#parse-pair) | Parses a string to form a pair. | Each argument has a **required** section which is denoted with `required` or `optional` * If it’s denoted by `required` it means the argument must be passed into that function before it'll work. * if it’s denoted by `optional` it means the function can work without passing the argument value. ## pair() Creates a pair from a key and value. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | --------- | -------- | ------------------------ | ----------------------------------------------- | | Key | string | Required | String for the key in the pair | | Value | string | Required | String for the value in the pair | | Separator | string | Optional (Default: ":") | Separator between the key and value in the pair | ### Returns Returns a pair with the key **Key** and the value **Value** with the separator **Seperator**. ### Examples ```kusto pair("key", "value", ".") ``` ```kusto ['logs'] | where tags contains pair("host", "mymachine") ``` [Run in Playground]() ## parse\_pair() Creates a pair from a key and value. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | --------- | -------- | ------------------------ | ----------------------------------------------- | | Pair | string | Required | String that has a pair of key value to pull out | | Separator | string | Optional (Default: ":") | Separator between the key and value in the pair | ### Returns Returns a pair with the key and value separated by the separator **Seperator** in **Pair**. If none is found a pair with the value of **Pair** and an empty key is returned. ### Examples ```kusto parse_pair("key.value", ".") ``` ```kusto ['logs'] | where parse_pair(tags[0]).key == "host" ``` [Run in Playground]() # Rounding functions Learn how to use and combine different rounding functions in APL ## Rounding functions | **Function Name** | **Description** | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | [ceiling()](#ceiling) | Calculates the smallest integer greater than, or equal to, the specified numeric expression. | | [bin()](#bin) | Rounds values down to an integer multiple of a given bin size. | | [bin\_auto()](#bin-auto) | Rounds values down to a fixed-size "bin", with control over the bin size and starting point provided by a query property. | | [floor()](#floor) | Calculates the largest integer less than, or equal to, the specified numeric expression. | ## ceiling() Calculates the smallest integer greater than, or equal to, the specified numeric expression. ### Arguments * x: A real number. ### Returns * The smallest integer greater than, or equal to, the specified numeric expression. ### Examples ```kusto ceiling(x) ``` ```kusto ceiling(25.43) == 26 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20smallest_integer%20%3D%20ceiling%2825.43%29%22%7D) ## bin() Rounds values down to an integer multiple of a given bin size. The `bin()` function is used with [summarize operator](/apl/tabular-operators/summarize-operator). If your set of values are disorderly, they will be grouped into fractions. ### Arguments * value: A date, number, or [timespan](/apl/data-types/scalar-data-types#timespan-literals) * roundTo: The "bin size", a number or timespan that divides value. ### Returns The nearest multiple of roundTo below value. ### Examples ```kusto bin(value,roundTo) ``` ```kusto bin(25.73, 4) == 24 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20round_value%20%3D%20bin%2825.73%2C%204%29%22%7D) ## bin\_auto() Rounds values down to a fixed-size "bin", the `bin_auto()` function can only be used with the [summarize operator](/apl/tabular-operators/summarize-operator) by statement with the `_time` column. ### Arguments * Expression: A scalar expression of a numeric type indicating the value to round. ### Returns The nearest multiple of `query_bin_auto_at` below Expression, shifted so that `query_bin_auto_at` will be translated into itself. ### Example ```kusto summarize count() by bin_auto(_time) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20summarize%20count%28%29%20by%20bin_auto%28_time%29%22%7D) ## floor() Calculates the largest integer less than, or equal to, the specified numeric expression. ### Arguments * number: A real number. ### Returns * The largest integer greater than, or equal to, the specified numeric expression. ### Examples ```kusto floor(number) ``` ```kusto floor(25.73) == 25 ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20largest_integer_number%20%3D%20floor%2825.73%29%22%7D) # SQL functions Learn how to use SQL functions in APL ## SQL functions | **Function Name** | **Description** | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | [parse\_sql()](#parse-sql) | Interprets and analyzes SQL queries, making it easier to extract and understand SQL statements within datasets. | | [format\_sql()](#format-sql) | Converts the data model produced by `parse_sql()` back into a SQL statement for validation or formatting purposes. | ## parse\_sql() Analyzes an SQL statement and constructs a data model, enabling insights into the SQL content within a dataset. ### Limitations * It is mainly used for simple SQL queries. SQL statements like stored procedures, Windows functions, common table expressions (CTEs), recursive queries, advanced statistical functions, and special joins are not supported. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------------- | -------- | ------------------------ | ----------------------------- | | sql\_statement | string | Required | The SQL statement to analyze. | ### Returns A dictionary representing the structured data model of the provided SQL statement. This model includes maps or slices that detail the various components of the SQL statement, such as tables, fields, conditions, etc. ### Examples ### Basic data retrieval The SQL statement **`SELECT * FROM db`** retrieves all columns and rows from the table named **`db`**. ```kusto hn | project parse_sql("select * from db") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\('select%20*%20from%20db'\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### WHERE Clause This example parses a **`SELECT`** statement with a **`WHERE`** clause, filtering **`customers`** by **`subscription_status`**. ```kusto hn | project parse_sql("SELECT id, email FROM customers WHERE subscription_status = 'active'") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20id%2C%20email%20FROM%20customers%20WHERE%20subscription_status%20%3D%20'active'%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### JOIN operation This example shows parsing an SQL statement that performs a **`JOIN`** operation between **`orders`** and **`customers`** tables to match orders with customer names. ```kusto hn | project parse_sql("SELECT orders.id, customers.name FROM orders JOIN customers ON orders.customer_id = customers.id") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20orders.id%2C%20customers.name%20FROM%20orders%20JOIN%20customers%20ON%20orders.customer_id%20%3D%20customers.id%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### GROUP BY Clause In this example, the **`parse_sql()`** function is used to parse an SQL statement that aggregates order counts by **`product_id`** using the **`GROUP BY`** clause. ```kusto hn | project parse_sql("SELECT product_id, COUNT(*) as order_count FROM orders GROUP BY product_id") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20product_id%2C%20COUNT\(*\)%20as%20order_count%20FROM%20orders%20GROUP%20BY%20product_id%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Nested Queries This example demonstrates parsing a nested SQL query, where the inner query selects **`user_id`** from **`orders`** based on **`purchase_date`**, and the outer query selects names from **`users`** based on those IDs. ```kusto hn | project parse_sql("SELECT name FROM users WHERE id IN (SELECT user_id FROM orders WHERE purchase_date > '2022-01-01')") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20name%20FROM%20users%20WHERE%20id%20IN%20\(SELECT%20user_id%20FROM%20orders%20WHERE%20purchase_date%20%3E%20'2022-01-01'\)%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### ORDER BY Clause Here, the example shows how to parse an SQL statement that orders **`users`** by **`registration_date`** in descending order. ```kusto hn | project parse_sql("SELECT name, registration_date FROM users ORDER BY registration_date DESC") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20name%2C%20registration_date%20FROM%20users%20ORDER%20BY%20registration_date%20DESC%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Sorting users by registration data This example demonstrates parsing an SQL statement that retrieves the **`name`** and **`registration_date`** of users from the **`users`** table, and orders the results by **`registration_date`** in descending order, showing how to sort data based on a specific column. ```kusto hn | extend parse_sql("SELECT name, registration_date FROM users ORDER BY registration_date DESC") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20extend%20parse_sql\(%5C%22SELECT%20name%2C%20registration_date%20FROM%20users%20ORDER%20BY%20registration_date%20DESC%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Querying with index hints to use a specific index This query hints at MySQL to use a specific index named **`index_name`** when executing the SELECT statement on the **`users`** table. ```kusto hn | project parse_sql("SELECT * FROM users USE INDEX (index_name) WHERE user_id = 101") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20*%20FROM%20users%20USE%20INDEX%20\(index_name\)%20WHERE%20user_id%20%3D%20101%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Inserting data with ON DUPLICATE KEY UPDATE This example showcases MySQL’s ability to handle duplicate key entries elegantly by updating the existing record if the insert operation encounters a duplicate key. ```kusto hn | project parse_sql("INSERT INTO settings (user_id, setting, value) VALUES (1, 'theme', 'dark') ON DUPLICATE KEY UPDATE value='dark'") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22INSERT%20INTO%20settings%20\(user_id%2C%20setting%2C%20value\)%20VALUES%20\(1%2C%20'theme'%2C%20'dark'\)%20ON%20DUPLICATE%20KEY%20UPDATE%20value%3D'dark'%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Using JSON functions This query demonstrates MySQL’s support for JSON data types and functions, extracting the age from a JSON object stored in the **`user_info`** column. ```kusto hn | project parse_sql("SELECT JSON_EXTRACT(user_info, '$.age') AS age FROM users WHERE user_id = 101") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20project%20parse_sql\(%5C%22SELECT%20JSON_EXTRACT\(user_info%2C%20%27%24.age%27\)%20AS%20age%20FROM%20users%20WHERE%20user_id%20%3D%20101%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ## format\_sql() Transforms the data model output by `parse_sql()` back into a SQL statement. Useful for testing and ensuring that the parsing accurately retains the original structure and intent of the SQL statement. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ------------------ | ---------- | ------------------------ | -------------------------------------------------- | | parsed\_sql\_model | dictionary | Required | The structured data model output by `parse_sql()`. | ### Returns A string that represents the SQL statement reconstructed from the provided data model. ### Examples ### Reformatting a basic SELECT Query After parsing a SQL statement, you can reformat it back to its original or a standard SQL format. ```kusto hn | extend parsed = parse_sql("SELECT * FROM db") | project formatted_sql = format_sql(parsed) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20extend%20parsed%20%3D%20parse_sql\(%5C%22SELECT%20*%20FROM%20db%5C%22\)%20%7C%20project%20formatted_sql%20%3D%20format_sql\(parsed\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Formatting SQL Queries This example first parses a SQL statement to analyze its structure and then formats the parsed structure back into a SQL string using `format_sql`. ```kusto hn | extend parsed = parse_sql("SELECT name, registration_date FROM users ORDER BY registration_date DESC") | project format_sql(parsed) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20extend%20parsed%20%3D%20parse_sql\(%5C%22SELECT%20name%2C%20registration_date%20FROM%20users%20ORDER%20BY%20registration_date%20DESC%5C%22\)%20%7C%20project%20formatted_sql%20%3D%20format_sql\(parsed\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Formatting a simple SELECT Statement This example demonstrates parsing a straightforward `SELECT` statement that retrieves user IDs and usernames from an `user_accounts` table where the `active` status is `1`. After parsing, it uses `format_sql` to convert the parsed data back into a SQL string. ```kusto hn | extend parsed = parse_sql("SELECT user_id, username FROM user_accounts WHERE active = 1") | project formatted_sql = format_sql(parsed) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20extend%20parsed%20%3D%20parse_sql\(%5C%22SELECT%20user_id%2C%20username%20FROM%20user_accounts%20WHERE%20active%20%3D%201%5C%22\)%20%7C%20project%20formatted_sql%20%3D%20format_sql\(parsed\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Reformatting a complex query with JOINS In this example, a more complex SQL statement involving an `INNER JOIN` between `orders` and `customers` tables is parsed. The query selects orders and customer names for orders placed after January 1, 2023. `format_sql` is then used to reformat the parsed structure into a SQL string. ```kusto hn | extend parsed = parse_sql("SELECT orders.order_id, customers.name FROM orders INNER JOIN customers ON orders.customer_id = customers.id WHERE orders.order_date > '2023-01-01'") | project formatted_sql = format_sql(parsed) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20extend%20parsed%20%3D%20parse_sql\(%5C%22SELECT%20orders.order_id%2C%20customers.name%20FROM%20orders%20INNER%20JOIN%20customers%20ON%20orders.customer_id%20%3D%20customers.id%20WHERE%20orders.order_date%20%3E%20'2023-01-01'%5C%22\)%20%7C%20project%20formatted_sql%20%3D%20format_sql\(parsed\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) ### Using format\_sql with aggregation functions This example focuses on parsing an SQL statement that performs aggregation. It selects product IDs and counts of total sales from a `sales` table, grouping by `product_id` and having a condition on the count. After parsing, `format_sql` reformats the output into an SQL string. ```kusto hn | extend parsed = parse_sql("SELECT product_id, COUNT(*) as total_sales FROM sales GROUP BY product_id HAVING COUNT(*) > 100") | project formatted_sql = format_sql(parsed) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22hn%20%7C%20extend%20parsed%20%3D%20parse_sql\(%5C%22SELECT%20product_id%2C%20COUNT\(*\)%20as%20total_sales%20FROM%20sales%20GROUP%20BY%20product_id%20HAVING%20COUNT\(*\)%20%3E%20100%5C%22\)%20%7C%20project%20formatted_sql%20%3D%20format_sql\(parsed\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D) # String functions Learn how to use and combine different string functions in APL ## String functions | **Function Name** | **Description** | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | [base64\_encode\_tostring()](#base64-encode-tostring) | Encodes a string as base64 string. | | [base64\_decode\_tostring()](#base64-decode-tostring) | Decodes a base64 string to a UTF-8 string. | | [countof()](#countof) | Counts occurrences of a substring in a string. | | [countof\_regex()](#countof-regex) | Counts occurrences of a substring in a string. Regex matches don’t. | | [coalesce()](#coalesce) | Evaluates a list of expressions and returns the first non-null (or non-empty for string) expression. | | [extract()](#extract) | Get a match for a regular expression from a text string. | | [extract\_all()](#extract-all) | Get all matches for a regular expression from a text string. | | [format\_bytes()](#format-bytes) | Formats a number of bytes as a string including bytes units | | [format\_url()](#format-url) | Formats an input string into a valid URL by adding the necessary protocol if it’s escaping illegal URL characters. | | [indexof()](#indexof) | Function reports the zero-based index of the first occurrence of a specified string within input string. | | [isempty()](#isempty) | Returns true if the argument is an empty string or is null. | | [isnotempty()](#isnotempty) | Returns true if the argument isn’t an empty string or a null. | | [isnotnull()](#isnotnull) | Returns true if the argument is not null. | | [isnull()](#isnull) | Evaluates its sole argument and returns a bool value indicating if the argument evaluates to a null value. | | [parse\_bytes()](#parse-bytes) | Parses a string including byte size units and returns the number of bytes | | [parse\_json()](#parse-json) | Interprets a string as a JSON value) and returns the value as dynamic. | | [parse\_url()](#parse-url) | Parses an absolute URL string and returns a dynamic object contains all parts of the URL. | | [parse\_urlquery()](#parse-urlquery) | Parses a url query string and returns a dynamic object contains the Query parameters. | | [replace()](#replace) | Replace all regex matches with another string. | | [replace\_regex()](#replace-regex) | Replaces all regex matches with another string. | | [replace\_string()](#replace-string) | Replaces all string matches with another string. | | [reverse()](#reverse) | Function makes reverse of input string. | | [split()](#split) | Splits a given string according to a given delimiter and returns a string array with the contained substrings. | | [strcat()](#strcat) | Concatenates between 1 and 64 arguments. | | [strcat\_delim()](#strcat-delim) | Concatenates between 2 and 64 arguments, with delimiter, provided as first argument. | | [strcmp()](#strcmp) | Compares two strings. | | [strlen()](#strlen) | Returns the length, in characters, of the input string. | | [strrep()](#strrep) | Repeats given string provided number of times (default = 1). | | [substring()](#substring) | Extracts a substring from a source string starting from some index to the end of the string. | | [toupper()](#toupper) | Converts a string to upper case. | | [tolower()](#tolower) | Converts a string to lower case. | | [trim()](#trim) | Removes all leading and trailing matches of the specified cutset. | | [trim\_regex()](#trim-regex) | Removes all leading and trailing matches of the specified regular expression. | | [trim\_end()](#trim-end) | Removes trailing match of the specified cutset. | | [trim\_end\_regex()](#trim-end-regex) | Removes trailing match of the specified regular expression. | | [trim\_start()](#trim-start) | Removes leading match of the specified cutset. | | [trim\_start\_regex()](#trim-start-regex) | Removes leading match of the specified regular expression. | | [url\_decode()](#url-decode) | The function converts encoded URL into a regular URL representation. | | [url\_encode()](#url-encode) | The function converts characters of the input URL into a format that can be transmitted over the Internet. | | [gettype()](#gettype) | Returns the runtime type of its single argument. | | [parse\_csv()](#parse-csv) | Splits a given string representing a single record of comma-separated values and returns a string array with these values. | Each argument has a **required** section which is denoted with `required` or `optional` * If it’s denoted by `required` it means the argument must be passed into that function before it'll work. * if it’s denoted by `optional` it means the function can work without passing the argument value. ## base64\_encode\_tostring() Encodes a string as base64 string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------------------------------------------------ | | String | string | Required | Input string or string field to be encoded as base64 string. | ### Returns Returns the string encoded as base64 string. * To decode base64 strings to UTF-8 strings, see [base64\_decode\_tostring()](#base64-decode-tostring) ### Examples ```kusto base64_encode_tostring(string) ``` ```kusto ['sample-http-logs'] | project encoded_base64_string = base64_encode_tostring(content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20encoded_base64_string%20%3D%20base64_encode_tostring\(content_type\)%22%7D) ## base64\_decode\_tostring() Decodes a base64 string to a UTF-8 string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------------------------------------------------------------ | | String | string | Required | Input string or string field to be decoded from base64 to UTF8-8 string. | ### Returns Returns UTF-8 string decoded from base64 string. * To encode strings to base64 string, see [base64\_encode\_tostring()](#base64-encode-tostring) ### Examples ```kusto base64_decode_tostring(string) ``` ```kusto ['sample-http-logs'] | project decoded_base64_string = base64_decode_tostring("VGhpcyBpcyBhbiBlbmNvZGVkIG1lc3NhZ2Uu") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20decoded_base64_string%20%3D%20base64_decode_tostring\(%5C%22VGhpcyBpcyBhbiBlbmNvZGVkIG1lc3NhZ2Uu%5C%22\)%22%7D) ## countof() Counts occurrences of a substring in a string. ### Arguments | **name** | **type** | **description** | **Required or Optional** | | ----------- | ---------- | ---------------------------------------- | ------------------------ | | text source | **string** | Source to count your occurences from | Required | | search | **string** | The plain string to match inside source. | Required | ### Returns The number of times that the search string can be matched. ### Examples ```kusto countof(search, text) ``` ```kusto ['sample-http-logs'] | project count = countof("con", "content_type") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20count%20%3D%20countof\(%5C%22con%5C%22%2C%20%5C%22content_type%5C%22\)%22%7D) ## countof\_regex() Counts occurrences of a substring in a string. regex matches don’t. ### Arguments * text source: A string. * regex search: regular expression to match inside your text source. ### Returns The number of times that the search string can be matched in the dataset. Regex matches do not. ### Examples ```kusto countof_regex(regex, text) ``` ```kusto ['sample-http-logs'] | project count = countof_regex("c.n", "content_type") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20count%20%3D%20countof_regex\(%5C%22c.n%5C%22%2C%20%5C%22content_type%5C%22\)%22%7D) ## coalesce() Evaluates a list of expressions and returns the first non-null (or non-empty for string) expression. ### Arguments | **name** | **type** | **description** | **Required or Optional** | | --------- | ---------- | ---------------------------------------- | ------------------------ | | arguments | **scalar** | The expression or field to be evaluated. | Required | ### Returns The value of the first argument whose value isn’t null (or not-empty for string expressions). ### Examples ```kusto ['sample-http-logs'] | project coalesced = coalesce(content_type, ['geo.city'], method) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20coalesced%20%3D%20coalesce\(content_type%2C%20%5B%27geo.city%27%5D%2C%20method\)%22%7D) ```kusto ['http-logs'] | project req_duration_ms, server_datacenter, predicate = coalesce(content_type, method, status) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20req_duration_ms%2C%20server_datacenter%2C%20predicate%20%3D%20coalesce\(content_type%2C%20method%2C%20status\)%22%7D) ## extract() Convert the extracted substring to the indicated type. ### Arguments | **name** | **type** | **description** | | ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | regex | **expression** | A regular expression. | | captureGroup | **int** | A positive `int` constant indicating the capture group to extract. 0 stands for the entire match, 1 for the value matched by the first '('parenthesis')' in the regular expression, 2 or more for subsequent parentheses. | | source | **string** | A string to search | ### Returns If regex finds a match in source: the substring matched against the indicated capture group captureGroup, optionally converted to typeLiteral. If there’s no match, or the type conversion fails: `-1` or `string error` ### Examples ```kusto extract(regex, captureGroup, source) ``` ```kusto ['sample-http-logs'] | project extract_sub = extract("^.{2,2}(.{4,4})", 1, content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20extract_sub%20%3D%20%20extract\(%5C%22%5E.%7B2%2C2%7D\(.%7B4%2C4%7D\)%5C%22%2C%201%2C%20content_type\)%22%7D) ```kusto extract("x=([0-9.]+)", 1, "axiom x=65.6|po") == "65.6" ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20extract_sub%20%3D%20%20extract\(%5C%22x%3D\(%5B0-9.%5D%2B\)%5C%22%2C%201%2C%20%5C%22axiom%20x%3D65.6%7Cpo%5C%22\)%20%3D%3D%20%5C%2265.6%5C%22%22%7D) ## extract\_all() retrieve a subset of matching groups. ### Arguments | **name** | **type** | **description** | **Required or Optional** | | ------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | regex | **expression** | A regular expression containing between one and 16 capture groups. Examples of a valid regex: @"(\d+)". Examples of an invalid regex: @"\d+" | Required | | captureGroups | **array** | A dynamic array constant that indicates the capture group to extract. Valid values are from 1 to the number of capturing groups in the regular expression. | optional | | source | **string** | A string to search | Required | ### Returns * If regex finds a match in source: Returns dynamic array including all matches against the indicated capture groups captureGroups, or all of capturing groups in the regex. * If number of captureGroups is 1: The returned array has a single dimension of matched values. * If number of captureGroups is more than 1: The returned array is a two-dimensional collection of multi-value matches per captureGroups selection, or all capture groups present in the regex if captureGroups is omitted. * If there’s no match: `-1` ### Examples ```kusto extract_all(regex, [captureGroups,] source) ``` ```kusto ['sample-http-logs'] | project extract_match = extract_all(@"(\w)(\w+)(\w)", dynamic([1,3]), content_type) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20extract_match%20%3D%20extract_all%28%40%5C%22%28%5C%5Cw%29%28%5C%5Cw%2B%29%28%5C%5Cw%29%5C%22%2C%20dynamic%28%5B1%2C3%5D%29%2C%20content_type%29%22%2C%20%22queryOptions%22%3A%20%7B%22quickRange%22%3A%20%2290d%22%7D%7D) ```kusto extract_all(@"(\w)(\w+)(\w)", dynamic([1,3]), content_type) == [["t", "t"],["c","v"]] ``` ## format\_bytes() Formats a number as a string representing data size in bytes. ### Arguments | **name** | **type** | **description** | **Required or Optional** | | --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | value | **number** | a number to be formatted as data size in bytes | Required | | precision | **number** | Number of digits the value will be rounded to. (default value is zero) | Optional | | units | **string** | Units of the target data size the string formatting will use (base 2 suffixes: `Bytes`, `KiB`, `KB`, `MiB`, `MB`, `GiB`, `GB`, `TiB`, `TB`, `PiB`, `EiB`, `ZiB`, `YiB`; base 10 suffixes: `kB` `MB` `GB` `TB` `PB` `EB` `ZB` `YB`). If the parameter is empty the units will be auto-selected based on input value. | Optional | | base | **number** | Either 2 or 10 to specify whether the prefix is calculated using 1000s or 1024s for each type. (default value is 2) | Optional | ### Returns * A formatted string for humans ### Examples ```kusto format_bytes( 4000, number, "['id']", num_comments ) == "3.9062500000000 KB" ``` ```kusto format_bytes(value [, precision [, units [, base]]]) format_bytes(1024) == "1 KB" format_bytes(8000000, 2, "MB", 10) == "8.00 MB" ``` ```kusto ['github-issues-event'] | project formated_bytes = format_bytes( 4783549035, number, "['id']", num_comments ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20formated_bytes%20%3D%20format_bytes\(4783549035%2C%20number%2C%20%5C%22%5B%27id%27%5D%5C%22%2C%20num_comments\)%22%7D) ## format\_url() Formats an input string into a valid URL. This function will return a string that is a properly formatted URL. ### Arguments | **name** | **type** | **description** | **Required or Optional** | | -------- | ----------- | ------------------------------------------ | ------------------------ | | url | **dynamic** | string input you want to format into a URL | Required | ### Returns * A string that represents a properly formatted URL. ### Examples ```kusto ['sample-http-logs'] | project formatted_url = format_url(dynamic({"scheme": "https", "host": "github.com", "path": "/axiomhq/next-axiom"}) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20formatted_url%20%3D%20format_url%28dynamic%28%7B%5C%22scheme%5C%22%3A%20%5C%22https%5C%22%2C%20%5C%22host%5C%22%3A%20%5C%22github.com%5C%22%2C%20%5C%22path%5C%22%3A%20%5C%22%2Faxiomhq%2Fnext-axiom%5C%22%7D%29%29%22%7D) ```kusto ['sample-http-logs'] | project formatted_url = format_url(dynamic({"scheme": "https", "host": "github.com", "path": "/axiomhq/next-axiom", "port": 443, "fragment": "axiom","user": "axiom", "password": "apl"})) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20formatted_url%20%3D%20format_url%28dynamic%28%7B%5C%22scheme%5C%22%3A%20%5C%22https%5C%22%2C%20%5C%22host%5C%22%3A%20%5C%22github.com%5C%22%2C%20%5C%22path%5C%22%3A%20%5C%22%2Faxiomhq%2Fnext-axiom%5C%22%2C%20%5C%22port%5C%22%3A%20443%2C%20%5C%22fragment%5C%22%3A%20%5C%22axiom%5C%22%2C%20%5C%22user%5C%22%3A%20%5C%22axiom%5C%22%2C%20%5C%22password%5C%22%3A%20%5C%22apl%5C%22%7D%29%29%22%7D) * These are all the supported keys when using the `format_url` function: scheme, host, port, fragment, user, password, query. ## indexof() Reports the zero-based index of the first occurrence of a specified string within the input string. ### Arguments | **name** | **type** | **description** | **usage** | | ------------ | -------------- | ------------------------------------------------------------------------------- | --------- | | source | **string** | Input string | Required | | lookup | **string** | String to look up | Required | | start\_index | **text** | Search start position. | Optional | | length | **characters** | Number of character positions to examine. A value of -1 means unlimited length. | Optional | | occurrence | **number** | The number of the occurrence. Default 1. | Optional | ### Returns * Zero-based index position of lookup. * Returns -1 if the string isn’t found in the input. ### Examples ```kusto indexof( body, ['id'], 2, 1, number ) == "-1" ``` ```kusto indexof(source,lookup[,start_index[,length[,occurrence]]]) indexof () ``` ```kusto ['github-issues-event'] | project occurrence = indexof( body, ['id'], 23, 5, number ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20occurrence%20%3D%20indexof%28%20body%2C%20%5B%27id%27%5D%2C%2023%2C%205%2C%20number%20%29%22%7D) ## isempty() Returns `true` if the argument is an empty string or is null. ### Returns Indicates whether the argument is an empty string or isnull. ### Examples ```kusto isempty("") == true ``` ```kusto isempty([value]) ``` ```kusto ['github-issues-event'] | project empty = isempty(num_comments) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20empty%20%3D%20isempty%28num_comments%29%22%7D) ## isnotempty() Returns `true` if the argument isn’t an empty string, and it isn’t null. ### Examples ```kusto isnotempty("") == false ``` ```kusto isnotempty([value]) notempty([value]) -- alias of isnotempty ``` ```kusto ['github-issues-event'] | project not_empty = isnotempty(num_comments) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20not_empty%20%3D%20isnotempty%28num_comments%29%22%7D) ## isnotnull() Returns `true` if the argument is not null. ### Examples ```kusto isnotnull( num_comments ) == true ``` ```kusto isnotnull([value]) notnull([value]) - alias for `isnotnull` ``` ```kusto ['github-issues-event'] | project not_null = isnotnull(num_comments) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20not_null%20%3D%20isnotnull%28num_comments%29%22%7D) ## isnull() Evaluates its sole argument and returns a bool value indicating if the argument evaluates to a null value. ### Returns True or false, depending on whether or not the value is null. ### Examples ```kusto isnull(Expr) ``` ```kusto ['github-issues-event'] | project is_null = isnull(creator) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20is_null%20%3D%20isnull%28creator%29%22%7D) ## parse\_bytes() Parses a string including byte size units and returns the number of bytes ### Arguments | **name** | **type** | **description** | **Required or Optional** | | ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | | bytes\_string | **string** | A string formated defining the number of bytes | Required | | base | **number** | (optional) Either 2 or 10 to specify whether the prefix is calculated using 1000s or 1024s for each type. (default value is 2) | Required | ### Returns * The number of bytes or zero if unable to parse ### Examples ```kusto parse_bytes(bytes_string [, base]) parse_bytes("1 KB") == 1024 parse_bytes("1 KB", 10) == 1000 parse_bytes("128 Bytes") == 128 parse_bytes("bad data") == 0 ``` ```kusto ['github-issues-event'] | extend parsed_bytes = parse_bytes("300 KB", 10) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20parsed_bytes%20%3D%20%20parse_bytes%28%5C%22300%20KB%5C%22%2C%2010%29%22%7D) ```kusto ['github-issues-event'] | project parsed_bytes = parse_bytes("300 KB", 10) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20parsed_bytes%20%3D%20%20parse_bytes%28%5C%22300%20KB%5C%22%2C%2010%29%22%7D) ## parse\_json() Interprets a string as a JSON value and returns the value as dynamic. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | --------- | -------- | ------------------------ | -------------------------------------------------------------------- | | Json Expr | string | Required | Expression that will be used, also represents a JSON-formatted value | ### Returns An object of type json that is determined by the value of json: * If json is of type string, and is a properly formatted JSON string, then the string is parsed, and the value produced is returned. * If json is of type string, but it isn’t a properly formatted JSON string, then the returned value is an object of type dynamic that holds the original string value. ### Examples ```kusto parse_json(json) ``` ```kusto ['vercel'] | extend parsed = parse_json('{"name":"vercel", "statuscode":200, "region": { "route": "usage streams", "number": 9 }}') ``` ```kusto ['github-issues-event'] | extend parsed = parse_json(creator) | where isnotnull( parsed) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20parsed%20%3D%20parse_json%28creator%29%5Cn%7C%20where%20isnotnull%28parsed%29%22%7D) ## parse\_url() Parses an absolute URL `string` and returns an object contains `URL parts.` ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------------------------------------------- | | URL | string | Required | A string represents a URL or the query part of the URL. | ### Returns An object of type dynamic that included the URL components: Scheme, Host, Port, Path, Username, Password, Query Parameters, Fragment. ### Examples ```kusto parse_url(url) ``` ```kusto ['sample-http-logs'] | extend ParsedURL = parse_url("https://www.example.com/path/to/page?query=example") | project Scheme = ParsedURL["scheme"], Host = ParsedURL["host"], Path = ParsedURL["path"], Query = ParsedURL["query"] ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20extend%20ParsedURL%20%3D%20parse_url%28%5C%22https%3A%2F%2Fwww.example.com%2Fpath%2Fto%2Fpage%3Fquery%3Dexample%5C%22%29%5Cn%7C%20project%20%5Cn%20%20Scheme%20%3D%20ParsedURL%5B%5C%22scheme%5C%22%5D%2C%5Cn%20%20Host%20%3D%20ParsedURL%5B%5C%22host%5C%22%5D%2C%5Cn%20%20Path%20%3D%20ParsedURL%5B%5C%22path%5C%22%5D%2C%5Cn%20%20Query%20%3D%20ParsedURL%5B%5C%22query%5C%22%5D%22%7D) * Result ```json { "Host": "www.example.com", "Path": "/path/to/page", "Query": { "query": "example" }, "Scheme": "https" } ``` ## parse\_urlquery() Returns a `dynamic` object contains the Query parameters. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | -------------------------------- | | Query | string | Required | A string represents a url query. | query: A string represents a url query ### Returns An object of type dynamic that includes the query parameters. ### Examples ```kusto parse_urlquery("a1=b1&a2=b2&a3=b3") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20extend%20ParsedURLQUERY%20%3D%20parse_urlquery%28%5C%22a1%3Db1%26a2%3Db2%26a3%3Db3%5C%22%29%22%7D) * Result ```json { "Result": { "a3": "b3", "a2": "b2", "a1": "b1" } } ``` ```kusto parse_urlquery(query) ``` ```kusto ['github-issues-event'] | project parsed = parse_urlquery("https://play.axiom.co/axiom-play-qf1k/explorer?qid=fUKgiQgLjKE-rd7wjy") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20parsed%20%3D%20parse_urlquery%28%5C%22https%3A%2F%2Fplay.axiom.co%2Faxiom-play-qf1k%2Fexplorer%3Fqid%3DfUKgiQgLjKE-rd7wjy%5C%22%29%22%7D) ## replace() Replace all regex matches with another string. ### Arguments * regex: The regular expression to search source. It can contain capture groups in '('parentheses')'. * rewrite: The replacement regex for any match made by matchingRegex. Use $0 to refer to the whole match, $1 for the first capture group, \$2 and so on for subsequent capture groups. * source: A string. ### Returns * source after replacing all matches of regex with evaluations of rewrite. Matches do not overlap. ### Examples ```kusto replace(regex, rewrite, source) ``` ```kusto ['sample-http-logs'] | project content_type, Comment = replace("[html]", "[censored]", method) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20content_type%2C%20Comment%20%3D%20replace%28%5C%22%5Bhtml%5D%5C%22%2C%20%5C%22%5Bcensored%5D%5C%22%2C%20method%29%22%7D) ## replace\_regex() Replaces all regex matches with another string. ### Arguments * regex: The regular expression to search text. * rewrite: The replacement regex for any match made by *matchingRegex*. * text: A string. ### Returns source after replacing all matches of regex with evaluations of rewrite. Matches do not overlap. ### Examples ```kusto replace_regex(@'^logging', 'axiom', 'logging-data') ``` * Result ```json { "replaced": "axiom-data" } ``` ```kusto replace_regex(regex, rewrite, text) ``` ```kusto ['github-issues-event'] | extend replaced = replace_regex(@'^logging', 'axiom', 'logging-data') ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20replaced_regex%20%3D%20replace_regex%28%40'%5Elogging'%2C%20'axiom'%2C%20'logging-data'%29%22%7D) ### Backreferences Backreferences match the same text as previously matched by a capturing group. With Backreferences, you can identify a repeated character or substring within a string. * Backreferences in APL is implemented using the `$` sign. #### Examples ```kusto ['github-issues-event'] | project backreferences = replace_regex(@'observability=(.+)', 'axiom=$1', creator) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%20%7C%20project%20backreferences%20%3D%20replace_regex\(%40'observability%3D\(.%2B\)'%2C%20'axiom%3D%241'%2C%20creator\)%22%7D) ## replace\_string() Replaces all string matches with another string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ----------------------------------------------------------------------- | | lookup | string | Required | A string which Axiom matches in `text` and replaces with `rewrite`. | | rewrite | string | Required | A string with which Axiom replaces parts of `text` that match `lookup`. | | text | string | Required | A string where Axiom replaces parts matching `lookup` with `rewrite`. | ### Returns `text` after replacing all matches of `lookup` with evaluations of `rewrite`. Matches don’t overlap. ### Examples ```kusto replace_string("github", "axiom", "The project is hosted on github") ``` * Result ```json { "replaced_string": "axiom" } ``` ```kusto replace_string(lookup, rewrite, text) ``` ```kusto ['sample-http-logs'] | extend replaced_string = replace_string("The project is hosted on github", "github", "axiom") | project replaced_string ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20replaced_string%20%3D%20replace_string%28%27github%27%2C%20%27axiom%27%2C%20%27The%20project%20is%20hosted%20on%20github%27%29%5Cn%7C%20project%20replaced_string%22%7D) ## reverse() Function reverses the order of the input Field. ### Arguments | **name** | **type** | **description** | **Required or Optional** | | -------- | -------- | ----------------- | ------------------------ | | Field | `string` | Field input value | Required | ### Returns The reverse order of a field value. ### Examples ```kusto reverse(value) ``` ```kusto project reversed = reverse("axiom") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20reversed_value%20%3D%20reverse%28'axiom'%29%22%7D) * Result ```json moixa ``` ## split() Splits a given string according to a given delimiter and returns a string array with the contained substrings. Optionally, a specific substring can be returned if exists. ### Arguments * source: The source string that will be split according to the given delimiter. * delimiter: The delimiter (Field) that will be used in order to split the source string. ### Returns * A string array that contains the substrings of the given source string that are delimited by the given delimiter. ### Examples ```kusto split(source, delimiter) ``` ```kusto project split_str = split("axiom_observability_monitoring", "_") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20split_str%20%3D%20split%28%5C%22axiom_observability_monitoring%5C%22%2C%20%5C%22_%5C%22%29%22%7D) * Result ```json { "split_str": ["axiom", "observability", "monitoring"] } ``` ## strcat() Concatenates between 1 and 64 arguments. If the arguments aren’t of string type, they'll be forcibly converted to string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ------------------------------- | | Expr | string | Required | Expressions to be concatenated. | ### Returns Arguments, concatenated to a single string. ### Examples ```kusto strcat(argument1, argument2[, argumentN]) ``` ```kusto ['github-issues-event'] | project stract_con = strcat( ['milestone.creator'], number ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20stract_con%20%3D%20strcat%28%20%5B'milestone.creator'%5D%2C%20number%20%29%22%7D) ```kusto ['github-issues-event'] | project stract_con = strcat( 'axiom', number ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20stract_con%20%3D%20strcat%28%20'axiom'%2C%20number%20%29%22%7D) * Result ```json { "stract_con": "axiom3249" } ``` ## strcat\_delim() Concatenates between 2 and 64 arguments, with delimiter, provided as first argument. * If arguments aren’t of string type, they'll be forcibly converted to string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ------------ | -------- | ------------------------ | --------------------------------------------------- | | delimiter | string | Required | string expression, which will be used as separator. | | argument1 .. | string | Required | Expressions to be concatenated. | ### Returns Arguments, concatenated to a single string with delimiter. ### Examples ```kusto strcat_delim(delimiter, argument1, argument2[ , argumentN]) ``` ```kusto ['github-issues-event'] | project strcat = strcat_delim(":", actor, creator) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20strcat%20%3D%20strcat_delim%28'%3A'%2C%20actor%2C%20creator%29%22%7D) ```kusto project strcat = strcat_delim(":", "axiom", "monitoring") ``` * Result ```json { "strcat": "axiom:monitoring" } ``` ## strcmp() Compares two strings. The function starts comparing the first character of each string. If they are equal to each other, it continues with the following pairs until the characters differ or until the end of shorter string is reached. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ----------------------------------- | | string1 | string | Required | first input string for comparison. | | string2 | string | Required | second input string for comparison. | ### Returns Returns an integral value indicating the relationship between the strings: * When the result is 0: The contents of both strings are equal. * When the result is -1: the first character that does not match has a lower value in string1 than in string2. * When the result is 1: the first character that does not match has a higher value in string1 than in string2. ### Examples ```kusto strcmp(string1, string2) ``` ```kusto ['github-issues-event'] | extend cmp = strcmp( body, repo ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20cmp%20%3D%20strcmp%28%20body%2C%20repo%20%29%22%7D) ```kusto project cmp = strcmp( "axiom", "observability") ``` * Result ```json { "input_string": -1 } ``` ## strlen() Returns the length, in characters, of the input string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | -------- | -------- | ------------------------ | ---------------------------------------------------------- | | source | string | Required | The source string that will be measured for string length. | ### Returns Returns the length, in characters, of the input string. ### Examples ```kusto strlen(source) ``` ```kusto project str_len = strlen("axiom") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20str_len%20%3D%20strlen\(%5C%22axiom%5C%22\)%22%7D) * Result ```json { "str_len": 5 } ``` ## strrep() Repeats given string provided amount of times. * In case if first or third argument is not of a string type, it will be forcibly converted to string. ### Arguments | **Name** | **Type** | **Required or Optional** | **Description** | | ---------- | -------- | ------------------------ | ----------------------------------------------------- | | value | Expr | Required | Inpute Expression | | multiplier | integer | Required | positive integer value (from 1 to 1024) | | delimiter | string | Optional | An optional string expression (default: empty string) | ### Returns * Value repeated for a specified number of times, concatenated with delimiter. * In case if multiplier is more than maximal allowed value (1024), input string will be repeated 1024 times. ### Examples ```kusto strrep(value,multiplier,[delimiter]) ``` ```kusto ['github-issues-event'] | extend repeat_string = strrep( repo, 5, "::" ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20repeat_string%20%3D%20strrep\(%20repo%2C%205%2C%20%5C%22%3A%3A%5C%22%20\)%22%7D) ```kusto project repeat_string = strrep( "axiom", 3, "::" ) ``` * Result ```json { "repeat_string": "axiom::axiom::axiom" } ``` ## substring() Extracts a substring from a source string starting from some index to the end of the string. ### Arguments * source: The source string that the substring will be taken from. * startingIndex: The zero-based starting character position of the requested substring. * length: A parameter that can be used to specify the requested number of characters in the substring. ### Returns A substring from the given string. The substring starts at startingIndex (zero-based) character position and continues to the end of the string or length characters if specified. ### Examples ```kusto substring(source, startingIndex [, length]) ``` ```kusto ['github-issues-event'] | extend extract_string = substring( repo, 4, 5 ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20extract_string%20%3D%20substring\(%20repo%2C%204%2C%205%20\)%22%7D) ```kusto project extract_string = substring( "axiom", 4, 5 ) ``` ```json { "extract_string": "m" } ``` ## toupper() Converts a string to upper case. ```kusto toupper("axiom") == "AXIOM" ``` ```kusto ['github-issues-event'] | project upper = toupper( body ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20upper%20%3D%20toupper\(%20body%20\)%22%7D) ## tolower() Converts a string to lower case. ```kusto tolower("AXIOM") == "axiom" ``` ```kusto ['github-issues-event'] | project low = tolower( body ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20low%20%3D%20tolower%28body%29%22%7D) ## trim() Removes all leading and trailing matches of the specified cutset. ### Arguments * source: A string. * cutset: A string containing the characters to be removed. ### Returns source after trimming matches of the cutset found in the beginning and/or the end of source. ### Examples ```kusto trim(source) ``` ```kusto ['github-issues-event'] | extend remove_leading_matches = trim( "locked", repo) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20remove_leading_matches%20%3D%20trim\(%5C%22locked%5C%22%2C%20repo\)%22%7D) ```kusto project remove_leading_matches = trim( "axiom", "observability") ``` * Result ```json { "remove_leading_matches": "bservability" } ``` ## trim\_regex() Removes all leading and trailing matches of the specified regular expression. ### Arguments * regex: String or regular expression to be trimmed from the beginning and/or the end of source. * source: A string. ### Returns source after trimming matches of regex found in the beginning and/or the end of source. ### Examples ```kusto trim_regex(regex, source) ``` ```kusto ['github-issues-event'] | extend remove_trailing_match_regex = trim_regex( "^github", action ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20extend%20remove_trailing_match_regex%20%3D%20trim_regex\(%5C%22%5Egithub%5C%22%2C%20action\)%22%7D) * Result ```json { "remove_trailing_match_regex": "closed" } ``` ## trim\_end() Removes trailing match of the specified cutset. ### Arguments * source: A string. * cutset: A string containing the characters to be removed.\` ### Returns source after trimming matches of the cutset found in the end of source. ### Examples ```kusto trim_end(source) ``` ```kusto ['github-issues-event'] | extend remove_cutset = trim_end(@"[^\w]+", body) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20extend%20remove_cutset%20%3D%20trim_end%28%40%5C%22%5B%5E%5C%5Cw%5D%2B%5C%22%2C%20body%29%22%7D) * Result ```json { "remove_cutset": "In [`9128d50`](https://7aa98788e07\n), **down**:\n- HTTP code: 0\n- Response time: 0 ms\n" } ``` ## trim\_end\_regex() Removes trailing match of the specified regular expression. ### Arguments * regex: String or regular expression to be trimmed from the end of source. * source: A string. ### Returns source after trimming matches of regex found in the end of source. ### Examples ```kusto trim_end_regex(regex, source) ``` ```kusto ['github-issues-event'] | project remove_cutset_regex = trim_end_regex( "^github", creator ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20remove_cutset_regex%20%3D%20trim_end_regex\(%20%5C%22%5Egithub%5C%22%2C%20creator%20\)%22%7D) * Result ```json { "remove_cutset_regex": "axiomhq" } ``` ## trim\_start() Removes leading match of the specified cutset. ### Arguments * source: A string. ### Returns * source after trimming match of the specified cutset found in the beginning of source. ### Examples ```kusto trim_start(source) ``` ```kusto ['github-issues-event'] | project remove_cutset = trim_start( "github", repo) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20remove_cutset%20%3D%20trim_start\(%20%5C%22github%5C%22%2C%20repo\)%22%7D) * Result ```json { "remove_cutset": "axiomhq/next-axiom" } ``` ## trim\_start\_regex() Removes leading match of the specified regular expression. ### Arguments * regex: String or regular expression to be trimmed from the beginning of source. * source: A string. ### Returns source after trimming match of regex found in the beginning of source. ### Examples ```kusto trim_start_regex(regex, source) ``` ```kusto ['github-issues-event'] | project remove_cutset = trim_start_regex( "github", repo) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20remove_cutset%20%3D%20trim_start_regex\(%20%5C%22github%5C%22%2C%20repo\)%22%7D) * Result ```json { "remove_cutset": "axiomhq/next-axiom" } ``` ## url\_decode() The function converts encoded URL into a to regular URL representation. ### Arguments * `encoded url:` encoded URL (string). ### Returns URL (string) in a regular representation. ### Examples ```kusto url_decode(encoded url) ``` ```kusto ['github-issues-event'] | project decoded_link = url_decode( "https://www.axiom.co/" ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20decoded_link%20%3D%20url_decode\(%20%5C%22https%3A%2F%2Fwww.axiom.co%2F%5C%22%20\)%22%7D) * Result ```json { "decoded_link": "https://www.axiom.co/" } ``` ## url\_encode() The function converts characters of the input URL into a format that can be transmitted over the Internet. ### Arguments * url: input URL (string). ### Returns URL (string) converted into a format that can be transmitted over the Internet. ### Examples ```kusto url_encode(url) ``` ```kusto ['github-issues-event'] | project encoded_url = url_encode( "https://www.axiom.co/" ) ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20encoded_url%20%3D%20url_encode\(%20%5C%22https%3A%2F%2Fwww.axiom.co%2F%5C%22%20\)%22%7D) * Result ```json { "encoded_link": "https%3A%2F%2Fwww.axiom.co%2F" } ``` ## gettype() Returns the runtime type of its single argument. ### Arguments * Expressions ### Returns A string representing the runtime type of its single argument. ### Examples | **Expression** | **Returns** | | ----------------------------------------- | -------------- | | gettype("lima") | **string** | | gettype(2222) | **int** | | gettype(5==5) | **bool** | | gettype(now()) | **datetime** | | gettype(parse\_json('67')) | **int** | | gettype(parse\_json(' "polish" ')) | **string** | | gettype(parse\_json(' \{"axiom":1234} ')) | **dictionary** | | gettype(parse\_json(' \[6, 7, 8] ')) | **array** | | gettype(456.98) | **real** | | gettype(parse\_json('')) | **null** | ## parse\_csv() Splits a given string representing a single record of comma-separated values and returns a string array with these values. ### Arguments * csv\_text: A string representing a single record of comma-separated values. ### Returns A string array that contains the split values. ### Examples ```kusto parse_csv("axiom,logging,observability") == [ "axiom", "logging", "observability" ] ``` ```kusto parse_csv("axiom, processing, language") == [ "axiom", "processing", "language" ] ``` ```kusto ['github-issues-event'] | project parse_csv("github, body, repo") ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%5Cn%7C%20project%20parse_csv\(%5C%22github%2C%20body%2C%20repo%5C%22\)%22%7D) # Logical operators Learn how to use and combine different logical operators in APL. ## Logical (binary) operators The following logical operators are supported between two values of the `bool` type: **These logical operators are sometimes referred-to as Boolean operators, and sometimes as binary operators. The names are all synonyms.** | **Operator name** | **Syntax** | **meaning** | | | ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- | - | | Equality | **==** | Yields `true` if both operands are non-null and equal to each other. Otherwise, `false.` | | | Inequality | **!=** | Yields `true` if either one (or both) of the operands are null, or they are not equal to each other. Otherwise, `true.` | | | Logical and | **and** | Yields `true` if both operands are `true.` | | | Logical or | **or** | Yields `true `if one of the operands is `true`, regardless of the other operand. | | # Numerical operators Learn how to use and combine numerical operators in APL. ## Numerical operators The types `int`, `long`, and `real` represent numerical types. The following operators can be used between pairs of these types: | **Operator** | **Description** | **Example** | | | ------------ | --------------------------------- | ------------------------------------------------ | - | | `+` | Add | `3.19 + 3.19`, `ago(10m) + 10m` | | | `-` | Subtract | `0.26 - 0.23` | | | `*` | Multiply | `1s * 5`, `5 * 5` | | | `/` | Divide | `10m / 1s`, `4 / 2` | | | `%` | Modulo | `10 % 3`, `5 % 2` | | | `<` | Less | `1 < 2`, `1 <= 1` | | | `>` | Greater | `0.23 > 0.22`, `10min > 1sec`, `now() > ago(1d)` | | | `==` | Equals | `3 == 3` | | | `!=` | Not equals | `2 != 1` | | | `<=` | Less or Equal | `5 <= 6` | | | `>=` | Greater or Equal | `7 >= 6` | | | `in` | Equals to one of the elements | `"abc" in ("123", "345", "abc")` | | | `!in` | Not equals to any of the elements | `"bca" !in ("123", "345", "abc")` | | # String operators Learn how to use and combine different query operators for searching string data types. ## String operators Axiom processing language provides you with different query operators for searching string data types. Below are the list of string operators we support on Axiom processing language. **Note:** The following abbreviations are used in the table below: * RHS = right hand side of the expression. * LHS = left hand side of the expression. Operators with an \_cs suffix are case sensitive When two operators do the same task, use the case-sensitive one for better performance. For example: * instead of `=~`, use `==` * instead of `in~`, use `in` * instead of `contains`, use `contains_cs` The table below shows the list of string operators supported by Axiom processing language: | **Operator** | **Description** | **Case-Sensitive** | **Example** | | ------------------- | --------------------------------------- | ------------------ | --------------------------------------- | | **==** | Equals | Yes | `"aBc" == "aBc"` | | **!=** | Not equals | Yes | `"abc" != "ABC"` | | **=\~** | Equals | No | `"abc" =~ "ABC"` | | **!\~** | Not equals | No | `"aBc" !~ "xyz"` | | **contains** | RHS occurs as a subsequence of LHS | No | `parentSpanId` contains `Span` | | **!contains** | RHS doesn’t occur in LHS | No | `parentSpanId` !contains `abc` | | **contains\_cs** | RHS occurs as a subsequence of LHS | Yes | `parentSpanId` contains\_cs "Id" | | **!contains\_cs** | RHS doesn’t occur in LHS | Yes | `parentSpanId` !contains\_cs "Id" | | **startswith** | RHS is an initial subsequence of LHS | No | `parentSpanId` startswith `parent` | | **!startswith** | RHS isn’t an initial subsequence of LHS | No | `parentSpanId` !startswith "Id" | | **startswith\_cs** | RHS is an initial subsequence of LHS | Yes | `parentSpanId` startswith\_cs "parent" | | **!startswith\_cs** | RHS isn’t an initial subsequence of LHS | Yes | `parentSpanId` !startswith\_cs "parent" | | **endswith** | RHS is a closing subsequence of LHS | No | `parentSpanId` endswith "Id" | | **!endswith** | RHS isn’t a closing subsequence of LHS | No | `parentSpanId` !endswith `Span` | | **endswith\_cs** | RHS is a closing subsequence of LHS | Yes | `parentSpanId` endswith\_cs `Id` | | **!endswith\_cs** | RHS isn’t a closing subsequence of LHS | Yes | `parentSpanId` !endswith\_cs `Span` | | **in** | Equals to one of the elements | Yes | `abc` in ("123", "345", "abc") | | **!in** | Not equals to any of the elements | Yes | "bca" !in ("123", "345", "abc") | | **in\~** | Equals to one of the elements | No | "abc" in\~ ("123", "345", "ABC") | | **!in\~** | Not equals to any of the elements | No | "bca" !in\~ ("123", "345", "ABC") | | **!matches regex** | LHS doesn’t contain a match for RHS | Yes | `parentSpanId` !matches regex `g.*r` | | **matches regex** | LHS contains a match for RHS | Yes | `parentSpanId` matches regex `g.*r` | | **has** | RHS is a whole term in LHS | No | `Content Type` has `text` | | **has\_cs** | RHS is a whole term in LHS | Yes | `Content Type` has\_cs `Text` | ## Use string operators efficiently String operators are fundamental in comparing, searching, or matching strings. Understanding the performance implications of different operators can significantly optimize your queries. Below are performance tips and query examples. ## Equality and Inequality Operators * Operators: `==`, `!=`, `=~`, `!~`, `in`, `!in`, `in~`, `!in~` Query Examples: ```kusto "get" == "get" "get" != "GET" "get" =~ "GET" "get" !~ "put" "get" in ("get", "put", "delete") ``` * Use `==` or `!=` for exact match comparisons when case sensitivity is important, as they are faster. * Use `=~` or `!~` for case-insensitive comparisons, or when the exact case is unknown. * Use `in` or `!in` for checking membership within a set of values, which can be efficient for a small set of values. ## Subsequence Matching Operators * Operators: `contains`, `!contains`, `contains_cs`, `!contains_cs`, `startswith`, `!startswith`, `startswith_cs`, `!startswith_cs`, `endswith`, `!endswith`, `endswith_cs`, `!endswith_cs`. Query Examples: ```kusto "parentSpanId" contains "Span" // True "parentSpanId" !contains "xyz" // True "parentSpanId" startswith "parent" // True "parentSpanId" endswith "Id" // True "parentSpanId" contains_cs "Span" // True if parentSpanId is "parentSpanId", False if parentSpanId is "parentspanid" or "PARENTSPANID" "parentSpanId" startswith_cs "parent" // True if parentSpanId is "parentSpanId", False if parentSpanId is "ParentSpanId" or "PARENTSPANID" "parentSpanId" endswith_cs "Id" // True if parentSpanId is "parentSpanId", False if parentSpanId is "parentspanid" or "PARENTSPANID" ``` * Use case-sensitive operators (`contains_cs`, `startswith_cs`, `endswith_cs`) when the case is known, as they are faster. ## Regular Expression Matching Operators * Operators: `matches regex`, `!matches regex` ```kusto "parentSpanId" matches regex "p.*Id" // True "parentSpanId" !matches regex "x.*z" // True ``` * Avoid complex regular expressions or use string operators for simple substring, prefix, or suffix matching. ## Term Matching Operators * Operators: `has`, `has_cs` Query Examples: ```kusto "content type" has "type" // True "content type" has_cs "Type" // False ``` * Use `has` or `has_cs` for term matching which can be more efficient than regular expression matching for simple term searches. * Use `has_cs` when the case is known, as it is faster due to case-sensitive matching. ## Best Practices * Always use case-sensitive operators when the case is known, as they are faster. * Avoid complex regular expressions for simple matching tasks; use simpler string operators instead. * When matching against a set of values, ensure the set is as small as possible to improve performance. * For substring matching, prefer prefix or suffix matching over general substring matching for better performance. ## has operator The `has` operator in APL filters rows based on whether a given term or phrase appears within a string field. ## Importance of the `has` operator: * **Precision Filtering:** Unlike the `contains` operator, which matches any substring, the `has` operator looks for exact terms, ensuring more precise results. * **Simplicity:** Provides an easy and readable way to find exact terms in a string without resorting to regex or other more complex methods. The following table compares the `has` operators using the abbreviations provided: * RHS = right-hand side of the expression * LHS = left-hand side of the expression | Operator | Description | Case-Sensitive | Example | | ------------- | ------------------------------------------------------------- | -------------- | -------------------------------------- | | has | Right-hand-side (RHS) is a whole term in left-hand-side (LHS) | No | "North America" has "america" | | has\_cs | RHS is a whole term in LHS | Yes | "North America" has\_cs "America" | | hassuffix | LHS string ends with the RHS string | No | "documentation.docx" hassuffix ".docx" | | hasprefix | LHS string starts with the RHS string | No | "Admin\_User" hasprefix "Admin" | | hassuffix\_cs | LHS string ends with the RHS string | Yes | "Document.HTML" hassuffix\_cs ".HTML" | | hasprefix\_cs | LHS string starts with the RHS string | Yes | "DOCS\_file" hasprefix\_cs "DOCS" | ## Syntax ```kusto ['Dataset'] | where Field has (Expression) ``` ## Parameters | Name | Type | Required | Description | | ---------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | Field | string | ✓ | The field filters the events. | | Expression | scalar or tabular | ✓ | An expression for which to search. The first field is used if the value of the expression has multiple fields. | ## Returns The `has` operator returns rows from the dataset where the specified term is found in the given field. If the term is present, the row is included in the result set; otherwise, it is filtered out. ## Example ```kusto ['sample-http-logs'] | summarize event_count = count() by content_type | where content_type has "text" | where event_count > 10 | project event_count, content_type ``` [Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20summarize%20event_count%20%3D%20count%28%29%20by%20content_type%5Cn%7C%20where%20content_type%20has%20%5C%22text%5C%22%5Cn%7C%20where%20event_count%20%3E%2010%5Cn%7C%20project%20event_count%2C%20content_type%22%7D\&queryOptions=%7B%22quickRange%22%3A%2230d%22%7D) ## Output | event\_count | content\_type | | ------------ | ------------------------ | | 132,765 | text/html | | 132,621 | text/plain-charset=utf-8 | | 89,085 | text/csv | | 88,436 | text/css | # count This page explains how to use the count operator function in APL. The `count` operator in Axiom Processing Language (APL) is a simple yet powerful aggregation function that returns the total number of records in a dataset. You can use it to calculate the number of rows in a table or the results of a query. The `count` operator is useful in scenarios such as log analysis, telemetry data processing, and security monitoring, where you need to know how many events, transactions, or data entries match certain criteria. ## For users of other query languages If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
## Commonly used Operators
To run queries on each function or operator in this tutorial, click the **Run in Playground** button.
[summarize](/apl/tabular-operators/summarize-operator): Produces a table that aggregates the content of the dataset.
The following query returns the count of events by **time**
```kusto
['github-push-event']
| summarize count() by bin_auto(_time)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-push-event%27%5D%5Cn%7C%20summarize%20count%28%29%20by%20bin_auto%28_time%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
You can use the [aggregation functions](/apl/aggregation-function/statistical-functions) with the **summarize operator** to produce different columns.
## Top 10 GitHub push events by maximum push id
```kusto
['github-push-event']
| summarize max_if = maxif(push_id, true) by size
| top 10 by max_if desc
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-push-event%27%5D%5Cn%7C%20summarize%20max_if%20%3D%20maxif%28push_id%2C%20true%29%20by%20size%5Cn%7C%20top%2010%20by%20max_if%20desc%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Distinct City count by server datacenter
```kusto
['sample-http-logs']
| summarize cities = dcount(['geo.city']) by server_datacenter
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20summarize%20cities%20%3D%20dcount%28%5B%27geo.city%27%5D%29%20by%20server_datacenter%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
The result of a summarize operation has:
* A row for every combination of by values
* Each column named in by
* A column for each expression
[where](/apl/tabular-operators/where-operator): Filters the content of the dataset that meets a **condition** when executed.
The following query filters the data by **method** and **content\_type**:
```kusto
['sample-http-logs']
| where method == "GET" and content_type == "application/octet-stream"
| project method , content_type
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20method%20%3D%3D%20%5C%22GET%5C%22%20and%20content_type%20%3D%3D%20%5C%22application%2Foctet-stream%5C%22%5Cn%7C%20project%20method%20%2C%20content_type%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
[count](/apl/tabular-operators/count-operator): Returns the number of events from the input dataset.
```kusto
['sample-http-logs']
| count
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20count%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
[Summarize](/apl/tabular-operators/summarize-operator) count by time bins in sample HTTP logs
```kusto
['sample-http-logs']
| summarize count() by bin_auto(_time)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20summarize%20count%28%29%20by%20bin_auto%28_time%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
[project](/apl/tabular-operators/project-operator): Selects a subset of columns.
```kusto
['sample-http-logs']
| project content_type, ['geo.country'], method, resp_body_size_bytes, resp_header_size_bytes
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20content_type%2C%20%5B%27geo.country%27%5D%2C%20method%2C%20resp_body_size_bytes%2C%20resp_header_size_bytes%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
[take](/apl/tabular-operators/take-operator): Returns up to the specified number of rows.
```kusto
['sample-http-logs']
| take 100
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20take%20100%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
The **limit** operator is an alias to the **take** operator.
```kusto
['sample-http-logs']
| limit 10
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20limit%2010%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Scalar Functions
#### [parse\_json()](/apl/scalar-functions/string-functions#parse-json)
The following query extracts the JSON elements from an array:
```kusto
['sample-http-logs']
| project parsed_json = parse_json( "config_jsonified_metrics")
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20parsed_json%20%3D%20parse_json%28%20%5C%22config_jsonified_metrics%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
#### [replace\_string()](/apl/scalar-functions/string-functions#parse-json): Replaces all string matches with another string.
```kusto
['sample-http-logs']
| extend replaced_string = replace_string( "creator", "method", "machala" )
| project replaced_string
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20replaced_string%20%3D%20replace_string%28%20%5C%22creator%5C%22%2C%20%5C%22method%5C%22%2C%20%5C%22machala%5C%22%20%29%5Cn%7C%20project%20replaced_string%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
#### [split()](/apl/scalar-functions/string-functions#split): Splits a given string according to a given delimiter and returns a string array.
```kusto
['sample-http-logs']
| project split_str = split("method_content_metrics", "_")
| take 20
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20split_str%20%3D%20split%28%5C%22method_content_metrics%5C%22%2C%20%5C%22_%5C%22%29%5Cn%7C%20take%2020%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
#### [strcat\_delim()](/apl/scalar-functions/string-functions#strcat-delim): Concatenates a string array into a string with a given delimiter.
```kusto
['sample-http-logs']
| project strcat = strcat_delim(":", ['geo.city'], resp_body_size_bytes)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20strcat%20%3D%20strcat_delim%28%5C%22%3A%5C%22%2C%20%5B%27geo.city%27%5D%2C%20resp_body_size_bytes%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
#### [indexof()](/apl/scalar-functions/string-functions#indexof): Reports the zero-based index of the first occurrence of a specified string within the input string.
```kusto
['sample-http-logs']
| extend based_index = indexof( ['geo.country'], content_type, 45, 60, resp_body_size_bytes ), specified_time = bin(resp_header_size_bytes, 30)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20based_index%20%3D%20%20indexof%28%20%5B%27geo.country%27%5D%2C%20content_type%2C%2045%2C%2060%2C%20resp_body_size_bytes%20%29%2C%20specified_time%20%3D%20bin%28resp_header_size_bytes%2C%2030%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Regex Examples
```kusto
['sample-http-logs']
| project remove_cutset = trim_start_regex("[^a-zA-Z]", content_type )
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20remove_cutset%20%3D%20trim_start_regex%28%5C%22%5B%5Ea-zA-Z%5D%5C%22%2C%20content_type%20%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Finding logs from a specific City
```kusto
['sample-http-logs']
| where tostring(geo.city) matches regex "^Camaquã$"
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20tostring%28%5B%27geo.city%27%5D%29%20matches%20regex%20%5C%22%5ECamaqu%C3%A3%24%5C%22%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Identifying logs from a specific user agent
```kusto
['sample-http-logs']
| where tostring(user_agent) matches regex "Mozilla/5.0"
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20tostring%28user_agent%29%20matches%20regex%20%5C%22Mozilla%2F5.0%5C%22%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Finding logs with response body size in a certain range
```kusto
['sample-http-logs']
| where toint(resp_body_size_bytes) >= 4000 and toint(resp_body_size_bytes) <= 5000
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20toint%28resp_body_size_bytes%29%20%3E%3D%204000%20and%20toint%28resp_body_size_bytes%29%20%3C%3D%205000%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Finding logs with user agents containing Windows NT
```kusto
['sample-http-logs']
| where tostring(user_agent) matches regex @"Windows NT [\d\.]+"
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?qid=m8yNkSVVjGq-s0z19c)
## Finding logs with specific response header size
```kusto
['sample-http-logs']
| where toint(resp_header_size_bytes) == 31
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20toint%28resp_header_size_bytes%29%20%3D%3D%2031%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Finding logs with specific request duration
```kusto
['sample-http-logs']
| where toreal(req_duration_ms) < 1
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20toreal%28req_duration_ms%29%20%3C%201%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Finding logs where TLS is enabled and method is POST
```kusto
['sample-http-logs']
| where tostring(is_tls) == "true" and tostring(method) == "POST"
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20tostring%28is_tls%29%20%3D%3D%20%5C%22true%5C%22%20and%20tostring%28method%29%20%3D%3D%20%5C%22POST%5C%22%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Array functions
#### [array\_concat()](/apl/scalar-functions/array-functions#array_concat): Concatenates a number of dynamic arrays to a single array.
```kusto
['sample-http-logs']
| extend concatenate = array_concat( dynamic([5,4,3,87,45,2,3,45]))
| project concatenate
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20concatenate%20%3D%20array_concat%28%20dynamic%28%5B5%2C4%2C3%2C87%2C45%2C2%2C3%2C45%5D%29%29%5Cn%7C%20project%20concatenate%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
#### [array\_sum()](/apl/scalar-functions/array-functions#array-sum): Calculates the sum of elements in a dynamic array.
```kusto
['sample-http-logs']
| extend summary_array=dynamic([1,2,3,4])
| project summary_array=array_sum(summary_array)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20summary_array%3Ddynamic%28%5B1%2C2%2C3%2C4%5D%29%5Cn%7C%20project%20summary_array%3Darray_sum%28summary_array%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Conversion functions
#### [todatetime()](/apl/scalar-functions/conversion-functions#todatetime): Converts input to datetime scalar.
```kusto
['sample-http-logs']
| extend dated_time = todatetime("2026-08-16")
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20dated_time%20%3D%20todatetime%28%5C%222026-08-16%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
#### [dynamic\_to\_json()](/apl/scalar-functions/conversion-functions#dynamic-to-json): Converts a scalar value of type dynamic to a canonical string representation.
```kusto
['sample-http-logs']
| extend dynamic_string = dynamic_to_json(dynamic([10,20,30,40 ]))
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20dynamic_string%20%3D%20dynamic_to_json%28dynamic%28%5B10%2C20%2C30%2C40%20%5D%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## String Operators
[We support various query string](/apl/scalar-operators/string-operators), [logical](/apl/scalar-operators/logical-operators) and [numerical operators](/apl/scalar-operators/numerical-operators).
In the query below, we use the **contains** operator, to find the strings that contain the string **-bot** and **\[bot]**:
```kusto
['github-issue-comment-event']
| extend bot = actor contains "-bot" or actor contains "[bot]"
| where bot == true
| summarize count() by bin_auto(_time), actor
| take 20
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issue-comment-event%27%5D%5Cn%7C%20extend%20bot%20%3D%20actor%20contains%20%5C%22-bot%5C%22%20or%20actor%20contains%20%5C%22%5Bbot%5D%5C%22%5Cn%7C%20where%20bot%20%3D%3D%20true%5Cn%7C%20summarize%20count%28%29%20by%20bin_auto%28_time%29%2C%20actor%5Cn%7C%20take%2020%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
```kusto
['sample-http-logs']
| extend user_status = status contains "200" , agent_flow = user_agent contains "(Windows NT 6.4; AppleWebKit/537.36 Chrome/41.0.2225.0 Safari/537.36"
| where user_status == true
| summarize count() by bin_auto(_time), status
| take 15
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20user_status%20%3D%20status%20contains%20%5C%22200%5C%22%20%2C%20agent_flow%20%3D%20user_agent%20contains%20%5C%22%28Windows%20NT%206.4%3B%20AppleWebKit%2F537.36%20Chrome%2F41.0.2225.0%20Safari%2F537.36%5C%22%5Cn%7C%20where%20user_status%20%3D%3D%20true%5Cn%7C%20summarize%20count%28%29%20by%20bin_auto%28_time%29%2C%20status%5Cn%7C%20take%2015%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Hash Functions
* [hash\_md5()](/apl/scalar-functions/hash-functions#hash-md5): Returns an MD5 hash value for the input value.
* [hash\_sha256()](/apl/scalar-functions/hash-functions#hash-sha256): Returns a sha256 hash value for the input value.
* [hash\_sha1()](/apl/scalar-functions/hash-functions#hash-sha1): Returns a sha1 hash value for the input value.
```kusto
['sample-http-logs']
| extend sha_256 = hash_md5( "resp_header_size_bytes" ), sha_1 = hash_sha1( content_type), md5 = hash_md5( method), sha512 = hash_sha512( "resp_header_size_bytes" )
| project sha_256, sha_1, md5, sha512
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20sha_256%20%3D%20hash_md5%28%20%5C%22resp_header_size_bytes%5C%22%20%29%2C%20sha_1%20%3D%20hash_sha1%28%20content_type%29%2C%20md5%20%3D%20hash_md5%28%20method%29%2C%20sha512%20%3D%20hash_sha512%28%20%5C%22resp_header_size_bytes%5C%22%20%29%5Cn%7C%20project%20sha_256%2C%20sha_1%2C%20md5%2C%20sha512%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## List all unique groups
```kusto
['sample-http-logs']
| distinct ['id'], is_tls
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20distinct%20%5B'id'%5D%2C%20is_tls%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Count of all events per service
```kusto
['sample-http-logs']
| summarize Count = count() by server_datacenter
| order by Count desc
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20summarize%20Count%20%3D%20count%28%29%20by%20server_datacenter%5Cn%7C%20order%20by%20Count%20desc%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Change the time clause
```kusto
['github-issues-event']
| where _time == ago(1m)
| summarize count(), sum(['milestone.number']) by _time=bin(_time, 1m)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20where%20_time%20%3D%3D%20ago%281m%29%5Cn%7C%20summarize%20count%28%29%2C%20sum%28%5B%27milestone.number%27%5D%29%20by%20_time%3Dbin%28_time%2C%201m%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Rounding functions
* [floor()](/apl/scalar-functions/rounding-functions#floor): Calculates the largest integer less than, or equal to, the specified numeric expression.
* [ceiling()](/apl/scalar-functions/rounding-functions#ceiling): Calculates the smallest integer greater than, or equal to, the specified numeric expression.
* [bin()](/apl/scalar-functions/rounding-functions#bin): Rounds values down to an integer multiple of a given bin size.
```kusto
['sample-http-logs']
| extend largest_integer_less = floor( resp_header_size_bytes ), smallest_integer_greater = ceiling( req_duration_ms ), integer_multiple = bin( resp_body_size_bytes, 5 )
| project largest_integer_less, smallest_integer_greater, integer_multiple
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20largest_integer_less%20%3D%20floor%28%20resp_header_size_bytes%20%29%2C%20smallest_integer_greater%20%3D%20ceiling%28%20req_duration_ms%20%29%2C%20integer_multiple%20%3D%20bin%28%20resp_body_size_bytes%2C%205%20%29%5Cn%7C%20project%20largest_integer_less%2C%20smallest_integer_greater%2C%20integer_multiple%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Truncate decimals using round function
```kusto
['sample-http-logs']
| project rounded_value = round(req_duration_ms, 2)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20rounded_value%20%3D%20round%28req_duration_ms%2C%202%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Truncate decimals using floor function
```kusto
['sample-http-logs']
| project floor_value = floor(resp_body_size_bytes), ceiling_value = ceiling(req_duration_ms)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20project%20floor_value%20%3D%20floor%28resp_body_size_bytes%29%2C%20ceiling_value%20%3D%20ceiling%28req_duration_ms%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## HTTP 5xx responses (day wise) for the last 7 days - one bar per day
```kusto
['sample-http-logs']
| where _time > ago(7d)
| where req_duration_ms >= 5 and req_duration_ms < 6
| summarize count(), histogram(resp_header_size_bytes, 20) by bin(_time, 1d)
| order by _time desc
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20where%20_time%20%3E%20ago\(7d\)%20%7C%20where%20req_duration_ms%20%3E%3D%205%20and%20req_duration_ms%20%3C%206%20%7C%20summarize%20count\(\)%2C%20histogram\(resp_header_size_bytes%2C%2020\)%20by%20bin\(_time%2C%201d\)%20%7C%20order%20by%20_time%20desc%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%227d%22%7D%7D)
## Implement a remapper on remote address logs
```kusto
['sample-http-logs']
| extend RemappedStatus = case(req_duration_ms >= 0.57, "new data", resp_body_size_bytes >= 1000, "size bytes", resp_header_size_bytes == 40, "header values", "doesntmatch")
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20extend%20RemappedStatus%20%3D%20case%28req_duration_ms%20%3E%3D%200.57%2C%20%5C%22new%20data%5C%22%2C%20resp_body_size_bytes%20%3E%3D%201000%2C%20%5C%22size%20bytes%5C%22%2C%20resp_header_size_bytes%20%3D%3D%2040%2C%20%5C%22header%20values%5C%22%2C%20%5C%22doesntmatch%5C%22%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Advanced aggregations
In this section, you will learn how to run queries using different functions and operators.
```kusto
['sample-http-logs']
| extend prospect = ['geo.city'] contains "Okayama" or uri contains "/api/v1/messages/back"
| extend possibility = server_datacenter contains "GRU" or status contains "301"
| summarize count(), topk( user_agent, 6 ) by bin(_time, 10d), ['geo.country']
| take 4
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20prospect%20%3D%20%5B%27geo.city%27%5D%20contains%20%5C%22Okayama%5C%22%20or%20uri%20contains%20%5C%22%2Fapi%2Fv1%2Fmessages%2Fback%5C%22%5Cn%7C%20extend%20possibility%20%3D%20server_datacenter%20contains%20%5C%22GRU%5C%22%20or%20status%20contains%20%5C%22301%5C%22%5Cn%7C%20summarize%20count%28%29%2C%20topk%28%20user_agent%2C%206%20%29%20by%20bin%28_time%2C%2010d%29%2C%20%5B%27geo.country%27%5D%5Cn%7C%20take%204%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Searching map fields
```kusto
['otel-demo-traces']
| where isnotnull( ['attributes.custom'])
| extend extra = tostring(['attributes.custom'])
| search extra:"0PUK6V6EV0"
| project _time, trace_id, name, ['attributes.custom']
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%5Cn%7C%20where%20isnotnull%28%20%5B'attributes.custom'%5D%29%5Cn%7C%20extend%20extra%20%3D%20tostring%28%5B'attributes.custom'%5D%29%5Cn%7C%20search%20extra%3A%5C%220PUK6V6EV0%5C%22%5Cn%7C%20project%20_time%2C%20trace_id%2C%20name%2C%20%5B'attributes.custom'%5D%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Configure Processing rules
```kusto
['sample-http-logs']
| where _sysTime > ago(1d)
| summarize count() by method
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20where%20_sysTime%20%3E%20ago%281d%29%5Cn%7C%20summarize%20count%28%29%20by%20method%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%221d%22%7D%7D)
## Return different values based on the evaluation of a condition
```kusto
['sample-http-logs']
| extend MemoryUsageStatus = iff(req_duration_ms > 10000, "Highest", "Normal")
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20MemoryUsageStatus%20%3D%20iff%28req_duration_ms%20%3E%2010000%2C%20%27Highest%27%2C%20%27Normal%27%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Working with different operators
```kusto
['hn']
| extend superman = text contains "superman" or title contains "superman"
| extend batman = text contains "batman" or title contains "batman"
| extend hero = case(
superman and batman, "both",
superman, "superman ", // spaces change the color
batman, "batman ",
"none")
| where (superman or batman) and not (batman and superman)
| summarize count(), topk(type, 3) by bin(_time, 30d), hero
| take 10
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20extend%20superman%20%3D%20text%20contains%20%5C%22superman%5C%22%20or%20title%20contains%20%5C%22superman%5C%22%5Cn%7C%20extend%20batman%20%3D%20text%20contains%20%5C%22batman%5C%22%20or%20title%20contains%20%5C%22batman%5C%22%5Cn%7C%20extend%20hero%20%3D%20case%28%5Cn%20%20%20%20superman%20and%20batman%2C%20%5C%22both%5C%22%2C%5Cn%20%20%20%20superman%2C%20%5C%22superman%20%20%20%5C%22%2C%20%2F%2F%20spaces%20change%20the%20color%5Cn%20%20%20%20batman%2C%20%5C%22batman%20%20%20%20%20%20%20%5C%22%2C%5Cn%20%20%20%20%5C%22none%5C%22%29%5Cn%7C%20where%20%28superman%20or%20batman%29%20and%20not%20%28batman%20and%20superman%29%5Cn%7C%20summarize%20count%28%29%2C%20topk%28type%2C%203%29%20by%20bin%28_time%2C%2030d%29%2C%20hero%5Cn%7C%20take%2010%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
```kusto
['sample-http-logs']
| summarize flow = dcount( content_type) by ['geo.country']
| take 50
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20summarize%20flow%20%3D%20dcount%28%20content_type%29%20by%20%5B%27geo.country%27%5D%5Cn%7C%20take%2050%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Get the JSON into a property bag using parse-json
```kusto
example
| where isnotnull(log)
| extend parsed_log = parse_json(log)
| project service, parsed_log.level, parsed_log.message
```
## Get average response using project keep function
```kusto
['sample-http-logs']
| where ['geo.country'] == "United States" or ['id'] == 'b2b1f597-0385-4fed-a911-140facb757ef'
| extend systematic_view = ceiling( resp_header_size_bytes )
| extend resp_avg = cos( resp_body_size_bytes )
| project-away systematic_view
| project-keep resp_avg
| take 5
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20where%20%5B'geo.country'%5D%20%3D%3D%20%5C%22United%20States%5C%22%20or%20%5B'id'%5D%20%3D%3D%20%5C%22b2b1f597-0385-4fed-a911-140facb757ef%5C%22%5Cn%7C%20extend%20systematic_view%20%3D%20ceiling%28%20resp_header_size_bytes%20%29%5Cn%7C%20extend%20resp_avg%20%3D%20cos%28%20resp_body_size_bytes%20%29%5Cn%7C%20project-away%20systematic_view%5Cn%7C%20project-keep%20resp_avg%5Cn%7C%20take%205%22%7D)
## Combine multiple percentiles into a single chart in APL
```kusto
['sample-http-logs']
| summarize percentiles_array(req_duration_ms, 50, 75, 90) by bin_auto(_time)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20summarize%20percentiles_array\(req_duration_ms%2C%2050%2C%2075%2C%2090\)%20by%20bin_auto\(_time\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Combine mathematical functions
```kusto
['sample-http-logs']
| extend tangent = tan( req_duration_ms ), cosine = cos( resp_header_size_bytes ), absolute_input = abs( req_duration_ms ), sine = sin( resp_header_size_bytes ), power_factor = pow( req_duration_ms, 4)
| extend angle_pi = degrees( resp_body_size_bytes ), pie = pi()
| project tangent, cosine, absolute_input, angle_pi, pie, sine, power_factor
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20extend%20tangent%20%3D%20tan%28%20req_duration_ms%20%29%2C%20cosine%20%3D%20cos%28%20resp_header_size_bytes%20%29%2C%20absolute_input%20%3D%20abs%28%20req_duration_ms%20%29%2C%20sine%20%3D%20sin%28%20resp_header_size_bytes%20%29%2C%20power_factor%20%3D%20pow%28%20req_duration_ms%2C%204%29%5Cn%7C%20extend%20angle_pi%20%3D%20degrees%28%20resp_body_size_bytes%20%29%2C%20pie%20%3D%20pi%28%29%5Cn%7C%20project%20tangent%2C%20cosine%2C%20absolute_input%2C%20angle_pi%2C%20pie%2C%20sine%2C%20power_factor%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
```kusto
['github-issues-event']
| where actor !endswith "[bot]"
| where repo startswith "kubernetes/"
| where action == "opened"
| summarize count() by bin_auto(_time)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20where%20actor%20%21endswith%20%5C%22%5Bbot%5D%5C%22%5Cn%7C%20where%20repo%20startswith%20%5C%22kubernetes%2F%5C%22%5Cn%7C%20where%20action%20%3D%3D%20%5C%22opened%5C%22%5Cn%7C%20summarize%20count%28%29%20by%20bin_auto%28_time%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Change global configuration attributes
```kusto
['sample-http-logs']
| extend status = coalesce(status, "info")
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20extend%20status%20%3D%20coalesce\(status%2C%20%5C%22info%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Set defualt value on event field
```kusto
['sample-http-logs']
| project status = case(
isnotnull(status) and status != "", content_type, // use the contenttype if it’s not null and not an empty string
"info" // default value
)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20project%20status%20%3D%20case\(isnotnull\(status\)%20and%20status%20!%3D%20%5C%22%5C%22%2C%20content_type%2C%20%5C%22info%5C%22\)%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)
## Extract nested payment amount from custom attributes map field
```kusto
['otel-demo-traces']
| extend amount = ['attributes.custom']['app.payment.amount']
| where isnotnull( amount)
| project _time, trace_id, name, amount, ['attributes.custom']
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20extend%20amount%20%3D%20%5B'attributes.custom'%5D%5B'app.payment.amount'%5D%20%7C%20where%20isnotnull\(%20amount\)%20%7C%20project%20_time%2C%20trace_id%2C%20name%2C%20amount%2C%20%5B'attributes.custom'%5D%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D)
## Filtering GitHub issues by label identifier
```kusto
['github-issues-event']
| extend data = tostring(labels)
| where labels contains "d73a4a"
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'github-issues-event'%5D%20%7C%20extend%20data%20%3D%20tostring\(labels\)%20%7C%20where%20labels%20contains%20'd73a4a'%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D)
## Aggregate trace counts by HTTP method attribute in custom map
```kusto
['otel-demo-traces']
| extend httpFlavor = tostring(['attributes.custom'])
| summarize Count=count() by ['attributes.http.method']
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20extend%20httpFlavor%20%3D%20tostring\(%5B'attributes.custom'%5D\)%20%7C%20summarize%20Count%3Dcount\(\)%20by%20%5B'attributes.http.method'%5D%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2290d%22%7D%7D)
# Connect Axiom with Cloudflare Logpush
Axiom gives you an all-at-once view of key Cloudflare Logpush metrics and logs, out of the box, with our dynamic Cloudflare Logpush dashboard.
Cloudflare Logpush is a feature that allows you to push HTTP request logs and other Cloudflare-generated logs directly to your desired storage, analytics, and monitoring solutions like Axiom. The integration with Axiom aims to provide real-time insights into web traffic, and operational issues, thereby helping to monitor and troubleshoot effectively.
## What’s Cloudflare Logpush?
Cloudflare Logpush enables Cloudflare users to automatically export their logs in JSON format to a variety of endpoints. This feature is incredibly useful for analytics, auditing, debugging, and monitoring the performance and security of websites. Types of logs you can export include HTTP request logs, firewall events, and more.
## Installing Cloudflare Logpush app
### Prerequisites
* An active Cloudflare Enterprise account
* API token or global API key
You can create a token that has access to a single zone, single account or a mix of all these, depending on your needs. For account access, the token must
have theses permissions:
* Logs: Edit
* Account settings: Read
For the zones, only edit permission is required for logs.
## Steps
* Log in to Cloudflare, go to your Cloudflare dashboard, and then select the Enterprise zone (domain) you want to enable Logpush for.
* Optionally, set filters and fields. You can filter logs by field (like Client IP, User Agent, etc.) and set the type of logs you want (for example, HTTP requests, firewall events).
* In Axiom, click **Settings**, select **Apps**, and install the Cloudflare Logpush app with the token you created from the profile settings in Cloudflare.
* You see your available accounts and zones. Select the Cloudflare datasets you want to subscribe to.
* The installation uses the Cloudflare API to create Logpush jobs for each selected dataset.
* After the installation completes, you can find the installed Logpush jobs at Cloudflare.
For zone-scoped Logpush jobs:
For account-scoped Logpush jobs:
* In the Axiom, you can see your Cloudflare Logpush dashboard.
Using Axiom with Cloudflare Logpush offers a powerful solution for real-time monitoring, observability, and analytics. Axiom can help you gain deep insights into your app’s performance, errors, and app bottlenecks.
### Benefits of using the Axiom Cloudflare Logpush Dashboard
* Real-time visibility into web performance: One of the most crucial features is the ability to see how your website or app is performing in real-time. The dashboard can show everything from page load times to error rates, giving you immediate insights that can help in timely decision-making.
* Actionable insights for troubleshooting: The dashboard doesn’t just provide raw data; it provides insights. Whether it’s an error that needs immediate fixing or performance metrics that show an error from your app, having this information readily available makes it easier to identify problems and resolve them swiftly.
* DNS metrics: Understanding the DNS requests, DNS queries, and DNS cache hit from your app is vital to track if there’s a request spike or get the total number of queries in your system.
* Centralized logging and error tracing: With logs coming in from various parts of your app stack, centralizing them within Axiom makes it easier to correlate events across different layers of your infrastructure. This is crucial for troubleshooting complex issues that may span multiple services or components.
## Supported Cloudflare Logpush Datasets
Axiom supports all the Cloudflare account-scoped datasets.
Zone-scoped
* DNS logs
* Firewall events
* HTTP requests
* NEL reports
* Spectrum events
Account-scoped
* Access requests
* Audit logs
* CASB Findings
* Device posture results
* DNS Firewall Logs
* Gateway DNS
* Gateway HTTP
* Gateway Network
* Magic IDS Detections
* Network Analytics Logs
* Workers Trace Events
* Zero Trust Network Session Logs
# Connect Axiom with Cloudflare Workers
Axiom gives you an all-at-once view of key Cloudflare worker’s metrics and logs, out of the box, with our Dynamic Cloudflare workers dashboard.
Axiom’s Cloudflare Workers app provides granular detail about the traffic coming in from your monitored sites. This includes edge requests, static resources, client auth, response duration, and status. Axiom gives you an all-at-once view of key Cloudflare worker’s metrics and logs, out of the box, with our Dynamic Cloudflare workers dashboard.
The data obtained with the Axiom dashboard gives you better insights into the state of your Cloudflare workers so you can easily monitor bad requests, popular URLs, cumulative execution time, successful requests, and more. The app is part of Axiom’s unified logging and observability platform, so you can easily track Cloudflare Workers edge requests alongside a comprehensive view of other resources in your Cloudflare worker environments.
## What is Cloudflare Workers
Cloudflare Workers is a serverless computing platform developed by Cloudflare. The Workers platform allows developers to deploy and run JavaScript code directly at the network edge in more than 200 data centers worldwide. This serverless architecture enables high performance, low latency, and efficient scaling for web apps and APIs.
## Sending Cloudflare Worker logs to Axiom
The Axiom Cloudflare worker repository plugin is available on [GitHub](https://github.com/axiomhq/axiom-cloudflare-workers).
1. Copy the contents of [src/worker.js](https://github.com/axiomhq/axiom-cloudflare-workers/blob/main/src/worker.js) into a new worker on Cloudflare.
2. Update the authentication variables to corresponding dataset and token:
```bash
const axiomDataset = "my-dataset" // Your Axiom dataset
const axiomToken = "xapt-xxx" // Your Axiom API token
```
* The dataset is where your Cloudflare worker logs will be stored. Create a dataset from the settings page in the Axiom UI.
* The Axiom token will be your API token with ingest and query permissions.
3. Add triggers for the worker, for example,, a route trigger:
* Navigate to the worker and click on the Triggers tab.
* Scroll down to Routes and click Add Route.
* Enter a route, for example,, \*.example.com, choose the related zone, then click Save.
## View Cloudflare Workers Logs
When requests are made to the routes you set up, the worker will be triggered, and you will see the logs delivered to your Axiom dataset.
# Connect Axiom with Grafana
Learn how to extend the functionality of Grafana by installing the Axiom data source plugin.
## What is a Grafana data source plugin?
Grafana is an open-source tool for time-series analytics, visualization, and alerting. It’s frequently used in DevOps and IT Operations roles to provide real-time information on system health and performance.
Data sources in Grafana are the actual databases or services where the data is stored. Grafana has a variety of data source plugins that connect Grafana to different types of databases or services. This enables Grafana to query those sources from display that data on its dashboards. The data sources can be anything from traditional SQL databases to time-series databases or metrics, and logs from Axiom.
A Grafana data source plugin extends the functionality of Grafana by allowing it to interact with a specific type of data source. These plugins enable users to extract data from a variety of different sources, not just those that come supported by default in Grafana.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to create, read, update, and delete datasets.
## Install the Axiom Grafana data source plugin on Grafana Cloud
* In Grafana, click Administration > Plugins in the side navigation menu to view installed plugins.
* In the filter bar, search for the Axiom plugin
* Click on the plugin logo.
* Click Install.
When the update is complete, a confirmation message is displayed, indicating that the installation was successful.
* The Axiom Grafana Plugin is also installable from the [Grafana Plugins page](https://grafana.com/grafana/plugins/axiomhq-axiom-datasource/)
## Install the Axiom Grafana data source plugin on local Grafana
The Axiom data source plugin for Grafana is [open source on GitHub](https://github.com/axiomhq/axiom-grafana). It can be installed via the Grafana CLI, or via Docker.
### Install the Axiom Grafana Plugin using Grafana CLI
```bash
grafana-cli plugins install axiomhq-axiom-datasource
```
### Install Via Docker
* Add the plugin to your `docker-compose.yml` or `Dockerfile`
* Set the environment variable `GF_INSTALL_PLUGINS` to include the plugin
Example:
`GF_INSTALL_PLUGINS="axiomhq-axiom-datasource"`
## Configuration
* Add a new data source in Grafana
* Select the Axiom data source type.
* Enter the previously generated API token.
* Save and test the data source.
## Build Queries with Query Editor
The Axiom data source Plugin provides a custom query editor to build and visualize your Axiom event data. After configuring the Axiom data source, start building visualizations from metrics and logs stored in Axiom.
* Create a new panel in Grafana by clicking on Add visualization
* Select the Axiom data source.
* Use the query editor to choose the desired metrics, dimensions, and filters.
## Benefits of the Axiom Grafana data source plugin
The Axiom Grafana data source plugin allows users to display and interact with their Axiom data directly from within Grafana. By doing so, it provides several advantages:
1. **Unified visualization:** The Axiom Grafana data source plugin allows users to utilize Grafana’s powerful visualization tools with Axiom’s data. This enables users to create, explore, and share dashboards which visually represent their Axiom logs and metrics.
2. **Rich Querying Capability:** Grafana has a powerful and flexible interface for building data queries. With the Axiom plugin, and leverage this capability to build complex queries against your Axiom data.
3. **Customizable Alerting:** Grafana’s alerting feature allows you to set alerts based on your queries' results, and set up custom alerts based on specific conditions in your Axiom log data.
4. **Sharing and Collaboration:** Grafana’s features for sharing and collaboration can help teams work together more effectively. Share Axiom data visualizations with others, collaborate on dashboards, and discuss insights directly in Grafana.
# Apps
Enrich you Axiom organization with dedicated apps.
This section walks you through a catalogue of dedicated apps that enrich your Axiom organization.
To use standard APIs and other data shippers like the Elasticsearch Bulk API, FluentBit log processor or Fluentd log collector, go to [Send data](/send-data/ingest) instead.
## Monitor Lambda functions and usage in Axiom
Having real-time visibility into your function logs is important because any duration between sending your lambda request and the execution time can cause a delay and adds to customer-facing latency. You need to be able to measure and track your Lambda invocations, maximum and minimum execution time, and all invocations by function.
The Axiom Lambda Extension gives you full visibility into the most important metrics and logs coming from your Lambda function out of the box without any further configuration required.
## Track cold start on your Lambda function
A cold start occurs when there’s a delay between your invocation and runtime created during the initialization process. During this period, there’s no available function instance to respond to an invocation. With the Axiom built-in Serverless AWS Lambda dashboard, you can track and see the effect of cold start on your Lambda functions and its impact on every Lambda function. This data lets you know when to take actionable steps, such as using provisioned concurrency or reducing function dependencies.
## Optimize slow-performing Lambda queries
Grouping logs with Lambda invocations and execution time by function provides insights into your events request and response pattern. You can extend your query to view when an invocation request is rejected and configure alerts to be notified on Serverless log patterns and Lambda function payloads. With the invocation request dashboard, you can monitor request function logs and see how your Lambda serverless functions process your events and Lambda queues over time.
## Detect timeout on your Lambda function
Axiom Lambda function monitors let you identify the different points of invocation failures, cold-start delays, and AWS Lambda errors on your Lambda functions. With standard function logs like invocations by function, and Lambda cold start, monitoring the rate of your execution time can alert you to be aware of a significant spike whenever an error occurs in your Lambda function.
## Smart filters
Axiom Lambda Serverless Smart Filters lets you easily filter down to specific AWS Lambda functions or Serverless projects and use saved queries to get deep insights on how functions are performing with a single click.
# Connect Axiom with Netlify
Integrating Axiom with Netlify to get a comprehensive observability experience for your Netlify projects. This app will give you a better understanding of how your Jamstack apps are performing.
Integrate Axiom with Netlify to get a comprehensive observability experience for your Netlify projects. This integration will give you a better understanding of how your Jamstack apps are performing.
You can easily monitor logs and metrics related to your website traffic, serverless functions, and app requests. The integration is easy to set up, and you don’t need to configure anything to get started.
With Axiom’s Zero-Config Observability app, you can see all your metrics in real-time, without sampling. That means you can get a complete view of your app’s performance without any gaps in data.
Axiom’s Netlify app is complete with a pre-built dashboard that gives you control over your Jamstack projects. You can use this dashboard to track key metrics and make informed decisions about your app’s performance.
Overall, the Axiom Netlify app makes it easy to monitor and optimize your Jamstack apps. However, do note that this integration is only available for Netlify customers enterprise-level plans where [Log Drains are supported](https://docs.netlify.com/monitor-sites/log-drains/).
## What is Netlify
Netlify is a platform for building highly-performant and dynamic websites, e-commerce stores, and web apps. Netlify automatically builds your site and deploys it across its global edge network.
The Netlify platform provides teams everything they need to take modern web projects from the first preview to full production.
## Sending logs to Axiom
The log events gotten from Axiom gives you better insight into the state of your Netlify sites environment so that you can easily monitor traffic volume, website configurations, function logs, resource usage, and more.
1. Simply login to your [Axiom account](https://app.axiom.co/), click on **Apps** from the **Settings** menu, select the **Netlify app** and click on **Install now**.
* It’ll redirect you to Netlify to authorize Axiom.
* Click **Authorize**, and then copy the integration token.
2. Log into your **Netlify Team Account**, click on your site settings and select **Log Drains**.
* In your log drain service, select **Axiom**, paste the integration token from Step 1, and then click **Connect**.
## App overview
### Traffic and function Logs
With Axiom, you can instrument, and actively monitor your Netlify sites, stream your build logs, and analyze your deployment process, or use our pre-build Netlify Dashboard to get an overview of all the important traffic data, usage, and metrics. Various logs will be produced when users collaborate and interact with your sites and websites hosted on Netlify. Axiom captures and ingests all these logs into the `netlify` dataset.
You can also drill down to your site source with our advanced query language and fork our dashboard to start building your own site monitors.
* Back in your Axiom datasets console you'll see all your traffic and function logs in your `netlify` dataset.
### Live stream logs
Stream your sites and app logs live, and filter them to see important information.
### Zero-config dashboard for your Netlify sites
Use our pre-build Netlify Dashboard to get an overview of all the important metrics. When ready, you can fork our dashboard and start building your own!
## Start logging Netlify Sites today
Axiom Netlify integration allows you to monitor, and log all of your sites, and apps in one place. With the Axiom app, you can quickly detect site errors, and get high-level insights into your Netlify projects.
* We welcome ideas, feedback, and collaboration, join us in our [Discord Community](http://axiom.co/discord) to share them with us.
# Connect Axiom with Tailscale
This page explains how to integrate Axiom with Tailscale.
Tailscale is a secure networking solution that allows you to create and manage a private network (tailnet), securely connecting all your devices.
Integrating Axiom with Tailscale allows you to stream your audit and network flow logs directly to Axiom seamlessly, unlocking powerful insights and analysis. Whether you’re conducting a security audit, optimizing performance, or ensuring compliance, Axiom’s Tailscale dashboard equips you with the tools to maintain a secure and efficient network, respond quickly to potential issues, and make informed decisions about your network configuration and usage.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
{/* list separator */}
* [Create a Tailscale account](https://login.tailscale.com/start).
## Setup
1. In Tailscale, go to the [configuration logs page](https://login.tailscale.com/admin/logs) of the admin console.
2. Add Axiom as a configuration log streaming destination in Tailscale. For more information, see the [Tailscale documentation](https://tailscale.com/kb/1255/log-streaming?q=stream#add-a-configuration-log-streaming-destination).
## Tailscale dashboard
Axiom displays the data it receives in a pre-built Tailscale dashboard that delivers immediate, actionable insights into your tailnet’s activity and health.
This comprehensive overview includes:
* **Log type distribution**: Understand the balance between configuration audit logs and network flow logs over time.
* **Top actions and hosts**: Identify the most common network actions and most active devices.
* **Traffic visualization**: View physical, virtual, and exit traffic patterns for both sources and destinations.
* **User activity tracking**: Monitor actions by user display name, email, and ID for security audits and compliance.
* **Configuration log stream**: Access a detailed audit trail of all configuration changes.
With these insights, you can:
* Quickly identify unusual network activity or traffic patterns.
* Track configuration changes and user actions.
* Monitor overall network health and performance.
* Investigate specific events or users as needed.
* Understand traffic distribution across your tailnet.
# Connect Axiom with Terraform
Provision and manage Axiom resources such as datasets and monitors with Terraform.
Axiom Terraform Provider lets you provision and manage Axiom resources (datasets, notifiers, monitors, and users) with Terraform. This means that you can programmatically create resources, access existing ones, and perform further infrastructure automation tasks.
Install the Axiom Terraform Provider from the [Terraform Registry](https://registry.terraform.io/providers/axiomhq/axiom/latest). To see the provider in action, check out the [example](https://github.com/axiomhq/terraform-provider-axiom/blob/main/example/main.tf).
This guide explains how to install the provider and perform some common procedures such as creating new resources and accessing existing ones. For the full API reference, see the [documentation in the Terraform Registry](https://registry.terraform.io/providers/axiomhq/axiom/latest/docs).
## Prerequisites
* [Sign up for a free Axiom account](https://app.axiom.co/register). All you need is an email address.
* [Create an advanced API token in Axiom](/reference/tokens#create-advanced-api-token) with the permissions to perform the actions you want to use Terraform for. For example, to use Terraform to create and update datasets, create the advanced API token with these permissions.
* [Create a Terraform account](https://app.terraform.io/signup/account).
* [Install the Terraform CLI](https://developer.hashicorp.com/terraform/cli).
## Install the provider
To install the Axiom Terraform Provider from the [Terraform Registry](https://registry.terraform.io/providers/axiomhq/axiom/latest), follow these steps:
1. Add the following code to your Terraform configuration file. Replace `API_TOKEN` with the Axiom API token you have generated. For added security, store the API token in an environment variable.
```hcl
terraform {
required_providers {
axiom = {
source = "axiomhq/axiom"
}
}
}
provider "axiom" {
api_token = "API_TOKEN"
}
```
2. In your terminal, go to the folder of your main Terraform configuration file, and then run the command `terraform init`.
## Create new resources
### Create dataset
To create a dataset in Axiom using the provider, add the following code to your Terraform configuration file. Customize the `name` and `description` fields.
```hcl
resource "axiom_dataset" "test_dataset" {
name = "test_dataset"
description = "This is a test dataset created by Terraform."
}
```
### Create notifier
To create a Slack notifier in Axiom using the provider, add the following code to your Terraform configuration file. Replace `SLACK_URL` with the webhook URL from your Slack instance. For more information on obtaining this URL, see the [Slack documentation](https://api.slack.com/messaging/webhooks).
```hcl
resource "axiom_notifier" "test_slack_notifier" {
name = "test_slack_notifier"
properties = {
slack = {
slack_url = "SLACK_URL"
}
}
}
```
To create a Discord notifier in Axiom using the provider, add the following code to your Terraform configuration file.
* Replace `DISCORD_CHANNEL` with the webhook URL from your Discord instance. For more information on obtaining this URL, see the [Discord documentation](https://discord.com/developers/resources/webhook).
* Replace `DISCORD_TOKEN` with your Discord API token. For more information on obtaining this token, see the [Discord documentation](https://discord.com/developers/topics/oauth2).
```hcl
resource "axiom_notifier" "test_discord_notifier" {
name = "test_discord_notifier"
properties = {
discord = {
discord_channel = "DISCORD_CHANNEL"
discord_token = "DISCORD_TOKEN"
}
}
}
```
To create an email notifier in Axiom using the provider, add the following code to your Terraform configuration file. Replace `EMAIL1` and `EMAIL2` with the email addresses you want to notify.
```hcl
resource "axiom_notifier" "test_email_notifier" {
name = "test_email_notifier"
properties = {
email= {
emails = ["EMAIL1","EMAIL2"]
}
}
}
```
For more information on the types of notifier you can create, see the [documentation in the Terraform Registry](https://registry.terraform.io/providers/axiomhq/axiom/latest/resources/notifier).
### Create monitor
To create a monitor in Axiom using the provider, add the following code to your Terraform configuration file and customize it:
```hcl
resource "axiom_monitor" "test_monitor" {
depends_on = [axiom_dataset.test_dataset, axiom_notifier.test_slack_notifier]
name = "test_monitor"
description = "This is a test monitor created by Terraform."
apl_query = "['test_dataset'] | summarize count() by bin_auto(_time)"
interval_minutes = 5
operator = "Above"
range_minutes = 5
threshold = 1
notifier_ids = [
axiom_notifier.test_slack_notifier.id
]
alert_on_no_data = false
notify_by_group = false
}
```
This example creates a monitor using the dataset `test_dataset` and the notifier `test_slack_notifier`. These are resources you have created and accessed in the sections above.
* Customize the `name` and the `description` fields.
* In the `apl_query` field, specify the APL query for the monitor.
For more information on these fields, see the [documentation in the Terraform Registry](https://registry.terraform.io/providers/axiomhq/axiom/latest/resources/monitor).
### Create user
To create a user in Axiom using the provider, add the following code to your Terraform configuration file. Customize the `name`, `email`, and `role` fields.
```hcl
resource "axiom_user" "test_user" {
name = "test_user"
email = "test@abc.com"
role = "user"
}
```
## Access existing resources
### Access existing dataset
To access an existing dataset, follow these steps:
1. Determine the ID of the Axiom dataset by sending a GET request to the [`datasets` endpoint of the Axiom API](/restapi/endpoints/getDatasets).
2. Add the following code to your Terraform configuration file. Replace `DATASET_ID` with the ID of the Axiom dataset.
```hcl
data "axiom_dataset" "test_dataset" {
id = "DATASET_ID"
}
```
### Access existing notifier
To access an existing notifier, follow these steps:
1. Determine the ID of the Axiom notifier by sending a GET request to the `notifiers` endpoint of the Axiom API.
2. Add the following code to your Terraform configuration file. Replace `NOTIFIER_ID` with the ID of the Axiom notifier.
```hcl
data "axiom_dataset" "test_slack_notifier" {
id = "NOTIFIER_ID"
}
```
### Access existing monitor
To access an existing monitor, follow these steps:
1. Determine the ID of the Axiom monitor by sending a GET request to the `monitors` endpoint of the Axiom API.
2. Add the following code to your Terraform configuration file. Replace `MONITOR_ID` with the ID of the Axiom monitor.
```hcl
data "axiom_monitor" "test_monitor" {
id = "MONITOR_ID"
}
```
### Access existing user
To access an existing user, follow these steps:
1. Determine the ID of the Axiom user by sending a GET request to the `users` endpoint of the Axiom API.
2. Add the following code to your Terraform configuration file. Replace `USER_ID` with the ID of the Axiom user.
```hcl
data "axiom_user" "test_user" {
id = "USER_ID"
}
```
# Connect Axiom with Vercel
Easily monitor data from requests, functions, and web vitals in one place to get the deepest observability experience for your Vercel projects.
Connect Axiom with Vercel to get the deepest observability experience for your Vercel projects.
Easily monitor data from requests, functions, and web vitals in one place. 100% live and 100% of your data, no sampling.
Axiom’s Vercel app ships with a pre-built dashboard and pre-installed monitors so you can be in complete control of your projects with minimal effort.
If you use Axiom Vercel integration, [annotations](/query-data/annotate-charts) are automatically created for deployments.
## What is Vercel?
Vercel is a platform for frontend frameworks and static sites, built to integrate with your headless content, commerce, or database.
Vercel provides a frictionless developer experience to take care of the hard things: deploying instantly, scaling automatically, and serving personalized content around the globe.
Vercel makes it easy for frontend teams to develop, preview, and ship delightful user experiences, where performance is the default.
## Send logs to Axiom
Simply install the [Axiom Vercel app from here](https://vercel.com/integrations/axiom) and be streaming logs and web vitals within minutes!
## App Overview
### Request and function logs
For both requests and serverless functions, Axiom automatically installs a [log drain](https://vercel.com/blog/log-drains) in your Vercel account to capture data live.
As users interact with your website, various logs will be produced. Axiom captures all these logs and ingests them into the `vercel` dataset. You can stream and analyze these logs live, or use our pre-build Vercel Dashboard to get an overview of all the important metrics. When you’re ready, you can fork our dashboard and start building your own!
For function logs, if you call `console.log`, `console.warn` or `console.error` in your function, the output will also be captured and made available as part of the log. You can use our extended query language, APL, to easily search these logs.
## Web vitals
Axiom supports capturing and analyzing Web Vital data directly from your user’s browser without any sampling and with more data than is available elsewhere. It is perfect to pair with Vercel’s in-built analytics when you want to get really deep into a specific problem or debug issues with a specific audience (user-agent, location, region, etc).
...
);
}
```
Logged in
; } ``` ### Server Components For Server Components, create a logger and make sure to call flush before returning: ```js import { Logger } from 'next-axiom'; export default async function ServerComponent() { const log = new Logger(); log.info('User logged in', { userId: 42 }); // ... other operations ... await log.flush(); returnLogged in
; } ``` ### Route Handlers For Route Handlers, wrapping your Route Handlers in `withAxiom` will add a logger to your request and automatically log exceptions: ```js import { withAxiom, AxiomRequest } from 'next-axiom'; export const GET = withAxiom((req: AxiomRequest) => { req.log.info('Login function called'); // You can create intermediate loggers const log = req.log.with({ scope: 'user' }); log.info('User logged in', { userId: 42 }); return NextResponse.json({ hello: 'world' }); }); ``` ## Use Next.js 12 for Web Vitals If you’re using Next.js version 12, follow the instructions below to integrate Axiom for logging and capturing Web Vitals data. In your `pages/_app.js` or `pages/_app.ts` and add the following line: ```js export { reportWebVitals } from 'next-axiom'; ``` ## Upgrade to Next.js 13 from Next.js 12 If you plan on upgrading to Next.js 13, you'll need to make specific changes to ensure compatibility: * Upgrade the next-axiom package to version `1.0.0` or higher: * Make sure any exported variables have the `NEXT_PUBLIC_ prefix`, for example,, `NEXT_PUBLIC_AXIOM_TOKEN`. * In client components, use the `useLogger` hook instead of the `log` prop. * For server-side components, you need to create an instance of the `Logger` and flush the logs before the component returns. * For Web Vitals tracking, you'll replace the previous method of capturing data. Remove the `reportWebVitals()` line and instead integrate the `AxiomWebVitals` component into your layout. ## Vercel Function logs 4KB limit The Vercel 4KB log limit refers to a restriction placed by Vercel on the size of log output generated by serverless functions running on their platform. The 4KB log limit means that each log entry produced by your function should be at most 4 Kilobytes in size. If your log output is larger than 4KB, you might experience truncation or missing logs. To log above this limit, you can send your function logs using [next-axiom](https://github.com/axiomhq/next-axiom). ## Parse JSON on the message field If you use a logging library in your Vercel project that prints JSON, your **message** field will contain a stringified and therefore escaped JSON object. * If your Vercel logs are encoded as JSON, they will look like this: ```json { "level": "error", "message": "{ \"message\": \"user signed in\", \"metadata\": { \"userId\": 2234, \"signInType\": \"sso-google\" }}", "request": { "host": "www.axiom.co", "id": "iad1:iad1::sgh2r-1655985890301-f7025aa764a9", "ip": "199.16.157.13", "method": "GET", "path": "/sign-in/google", "scheme": "https", "statusCode": 500, "teamName": "AxiomHQ", }, "vercel": { "deploymentId": "dpl_7UcdgdgNsdgbcPY3Lg6RoXPfA6xbo8", "deploymentURL": "axiom-bdsgvweie6au-axiomhq.vercel.app", "projectId": "prj_TxvF2SOZdgdgwJ2OBLnZH2QVw7f1Ih7", "projectName": "axiom-co", "region": "iad1", "route": "/signin/[id]", "source": "lambda-log" } } ``` * The **JSON** data in your **message** would be: ```json { "message": "user signed in", "metadata": { "userId": 2234, "signInType": "sso-google" } } ``` You can **parse** the JSON using the [parse\_json function](/apl/scalar-functions/string-functions#parse-json\(\)) and run queries against the **values** in the **message** field. ### Example ```kusto ['vercel'] | extend parsed = parse_json(message) ``` * You can select the field to **insert** into new columns using the [project operator](/apl/tabular-operators/project-operator) ```kusto ['vercel'] | extend parsed = parse_json('{"message":"user signed in", "metadata": { "userId": 2234, "SignInType": "sso-google" }}') | project parsed["message"] ``` ### More Examples * If you have **null values** in your data you can use the **isnotnull()** function ```kusto ['vercel'] | extend parsed = parse_json(message) | where isnotnull(parsed) | summarize count() by parsed["message"], parsed["metadata"]["userId"] ``` * Check out our [APL Documentation on how to use more functions](/apl/scalar-functions/string-functions) and run your own queries against your Vercel logs. ## Migrate from Vercel app to next-axiom In May 2024, Vercel [introduced higher costs](https://axiom.co/blog/changes-to-vercel-log-drains) for using Vercel Log Drains. Because the Axiom Vercel app depends on Log Drains, using the next-axiom library can be the cheaper option to analyze telemetry data for higher volume projects. To migrate from the Axiom Vercel app to the next-axiom library, follow these steps: 1. Delete the existing log drain from your Vercel project. 2. Delete `NEXT_PUBLIC_AXIOM_INGEST_ENDPOINT` from the environment variables of your Vercel project. For more information, see the [Vercel documentation](https://vercel.com/projects/environment-variables). 3. [Create a new dataset in Axiom](/reference/datasets), and [create a new advanced API token](/reference/tokens) with ingest permissions for that dataset. 4. Add the following environment variables to your Vercel project: * `NEXT_PUBLIC_AXIOM_DATASET` is the name of the Axiom dataset where you want to send data. * `NEXT_PUBLIC_AXIOM_TOKEN` is the Axiom API token you have generated. 5. In your terminal, go to the root folder of your Next.js app, and then run `npm install --save next-axiom` to install the latest version of next-axiom. 6. In the `next.config.ts` file, wrap your Next.js configuration in `withAxiom`: ```js const { withAxiom } = require('next-axiom'); module.exports = withAxiom({ // Your existing configuration }); ``` For more configuration options, see the [documentation in the next-axiom GitHub repository](https://github.com/axiomhq/next-axiom). ## Send logs from Vercel preview deployments To send logs from Vercel preview deployments to Axiom, enable preview deployments for the environment variable `NEXT_PUBLIC_AXIOM_INGEST_ENDPOINT`. For more information, see the [Vercel documentation](https://vercel.com/docs/projects/environment-variables/managing-environment-variables). # Configure dashboard elements This section explains how to configure dashboard elements. When you create a chart, click
to access the following options.
## Values
Specify how to treat missing or undefined values:
* **Auto:** This option automatically decides the best way to represent missing or undefined values in the data series based on the chart type and the rest of the data.
* **Ignore:** This option ignores any missing or undefined values in the data series. This means that the chart only displays the known, defined values.
* **Join adjacent values:** This option connects adjacent data points in the data series, effectively filling in any gaps caused by missing values. The benefit of joining adjacent values is that it can provide a smoother, more continuous visualization of your data.
* **Fill with zeros:** This option replaces any missing or undefined values in the data series with zero. This can be useful if you want to emphasize that the data is missing or undefined, as it causes a drop to zero in your chart.
## Variant
Specify the chart type.
**Area:** An area chart displays the area between the data line and the axes, often filled with a color or pattern. Stacked charts provide the capability to design and implement intricate query dashboards while integrating advanced visualizations, enriching your logging experience over time.
**Bars:** A bar chart represents data in rectangular bars. The length of each bar is proportional to the value it represents. Bar charts can be used to compare discrete quantities, or when you have categorical data.
**Line:** A line chart connects individual data points into a continuous line, which is useful for showing logs over time. Line charts are often used for time series data.
## Y-Axis
Specify the scale of the vertical axis.
**Linear:** A linear scale maintains a consistent scale where equal distances represent equal changes in value. This is the most common scale type and is useful for most types of data.
**Log:** A logarithmic (or log) scale represents values in terms of their order of magnitude. Each unit of distance on a log scale represents a tenfold increase in value. Log scales make it easy to see backend errors and compare values across a wide range.
## Annotations
Specify the types of annotations to display in the chart:
* Show all annotations
* Hide all annotations
* Selective determine the annotations types to display
# Create dashboard elements
This section explains how to create dashboard elements.
To create new dashboard elements:
1. [Create a dashboard](/dashboards/create) or open an existing dashboard.
2. Click 
**Add element** in the top right corner.
3. Choose the dashboard element from the list.
4. For charts, select one of the following:
* Click **Simple Query Builder** to create your chart using a [visual query builder](#create-chart-using-visual-query-builder).
* Click **Advanced Query Language** to create your chart using the Axiom Processing Language (APL). Create a chart in the same way you create a chart in the APL query builder of the [Query tab](/query-data/explore#create-a-query-using-apl).
5. Optional: [Configure chart options](/dashboard-elements/configure).
6. Optional: Set a custom time range that is different from the dashboard’s time range.
7. Click **Save**.
The new element appears in your dashboard. At the bottom, click **Save** to save your changes to the dashboard.
## Create chart using visual query builder
Use the query builder to create or edit queries for the selected dataset:
This component is a visual query builder that eases the process of building visualizations and segments of your data.
This guide walks you through the individual sections of the query builder.
### Time range
Every query has a start and end time and the time range component allows quick selection of common time ranges as well as the ability to input specific start and end timestamps:
* Use the **Quick Range** items to quickly select popular ranges
* Use the **Custom Start/End Date** inputs to select specific times
* Use the **Resolution** items to choose between various time bucket resolutions
### Against
When a time series visualization is selected, such as `count`, the **Against** menu is enabled and it’s possible to select a historical time to compare the results of your time range too.
For example, to compare the last hour’s average response time to the same time yesterday, select `1 hr` in the time range menu, and then select `-1D` from the **Against** menu:
The results look like this:
The dotted line represents results from the base date, and the totals table includes the comparative totals.
When you add `field` to the `group by` clause, the **time range against** values are attached to each `events`.
### Visualizations
Axiom provides powerful visualizations that display the output of running aggregate functions across your dataset. The Visualization menu allows you to add these visualizations and, where required, input their arguments:
You can select a visualization to add it to the query. If a visualization requires an argument (such as the field and/or other parameters), the menu allows you to select eligible fields and input those arguments. Press `Enter` to complete the addition:
Click Visualization in the query builder to edit it at any time.
[Learn about supported visualizations](/query-data/visualizations)
### Filters
Use the filter menu to attach filter clauses to your search.
Axiom supports AND/OR operators at the top-level as well as one level deep. This means you can create filters that would read as `status == 200 AND (method == get OR method == head) AND (user-agent contains Mozilla or user-agent contains Webkit)`.
Filters are divided up by the field type they operate on, but some may apply to more than one field type.
#### List of filters
*String Fields*
* `==`
* `!=`
* `exists`
* `not-exists`
* `starts-with`
* `not-starts-with`
* `ends-with`
* `not-ends-with`
* `contains`
* `not-contains`
* `regexp`
* `not-regexp`
*Number Fields*
* `==`
* `!=`
* `exists`
* `not-exists`
* `>`
* `>=`
* `<`
* `<=`
*Boolean Fields*
* `==`
* `!=`
* `exists`
* `not-exists`
*Array Fields*
* `contains`
* `not-contains`
* `exists`
* `not-exists`
#### Special fields
Axiom creates the following two fields automatically for a new dataset:
* `_time` is the timestamp of the event. If the data you ingest doesn’t have a `_time` field, Axiom assigns the time of the data ingest to the events.
* `_sysTime` is the time when you ingested the data.
In most cases, you can use `_time` and `_sysTime` interchangeably. The difference between them can be useful if you experience clock skews on your event-producing systems.
### Group by (segmentation)
When visualizing data, it can be useful to segment data into specific groups to more clearly understand how the data behaves.
The Group By component enables you to add one or more fields to group events by:
### Other options
#### Order
By default, Axiom automatically chooses the best ordering for results. However, you can manually set the desired order through this menu.
#### Limit
By default, Axiom chooses a reasonable limit for the query that has been passed in. However, you can control that limit manually through this component.
## Change element’s position
To change element’s position on the dashboard, drag the title bar of the chart.
## Change element size
To change the size of the element, drag the bottom-right corner.
## Set custom time range
You can set a custom time range for individual dashboard elements that is different from the dashboard’s time range. For example, the dashboard displays data about the last 30 minutes but individual dashboard elements display data for different time ranges. This can be useful for visualizing the same chart or statistic for different time periods, among others.
To set a custom time range for a dashboard element:
1. In the top right of the dashboard element, click 
**More >** 
**Edit**.
2. In the top right above the chart, click 
.
3. Click **Custom**.
4. Choose one of the following options:
* Use the **Quick range** items to quickly select popular time ranges.
* Use the **Custom start/end date** fields to select specific times.
5. Click **Save**.
Axiom displays the new time range in the top left of the dashboard element.
### Set custom time range in APL
To set a custom time range for dashboard elements created with APL, you can use the [procedure above](#set-custom-time-range) or define the time range in the APL query:
1. In the top right of the dashboard element, click **More >** **Edit**.
2. In the APL query, specify the custom time range using the [where](/apl/tabular-operators/where-operator) operator. For example:
```kusto
| where _time > now(-6h)
```
3. Click **Run query** to preview the result.
4. Click **Save**.
Axiom displays in the top left of the dashboard element to indicate that its time range is defined in the APL query and might be different from the dashboard’s time range.
# Heatmap
This section explains how to create heatmap dashboard elements and add them to your dashboard.
export const elementName_0 = "heatmap"
export const elementButtonLabel_0 = "Heatmap"
Heatmaps represent the distribution of numerical data by grouping values into ranges or buckets. Each bucket reflects a frequency count of data points that fall within its range. Instead of showing individual events or measurements, heatmaps give a clear view of the overall distribution patterns. This allows you to identify performance bottlenecks, outliers, or shifts in behavior. For instance, you can use heatmaps to track response times, latency, or error rates.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Send data](/send-data/ingest) to your Axiom dataset.
* [Create an empty dashboard](/dashboards/create).
## Create {elementName_0}
1. Go to the Dashboards tab and open the dashboard to which you want to add the {elementName_0}.
2. Click **Add element** in the top right corner.
3. Click **{elementButtonLabel_0}** from the list.
4. Choose one of the following:
* Click **Simple Query Builder** to create your chart using a visual query builder. For more information, see [Create chart using visual query builder](/dashboard-elements/create#create-chart-using-visual-query-builder).
* Click **Advanced Query Language** to create your chart using the Axiom Processing Language (APL). Create a chart in the same way you create a chart in the APL query builder of the [Query tab](/query-data/explore#create-a-query-using-apl).
5. Optional: [Configure the dashboard element](/dashboard-elements/configure).
6. Click **Save**.
The new element appears in your dashboard. At the bottom, click **Save** to save your changes to the dashboard.
## Example with Simple Query Builder
## Example with Advanced Query Language
```kusto
['http-logs']
| summarize histogram(req_duration_ms, 15) by bin_auto(_time)
```
# Log stream
This section explains how to create log stream dashboard elements and add them to your dashboard.
The log stream dashboard element displays your logs as they come in real-time. Each log appears as a separate line with various details. The benefit of a log stream is that it provides immediate visibility into your system’s operations. When you’re debugging an issue or trying to understand an ongoing event, the log stream allows you to see exactly what’s happening as it occurs.
## Example with Simple Query Builder
## Example with Advanced Query Language
```kusto
['sample-http-logs']
| project method, status, content_type
```
# Monitor list
This section explains how to create monitor list dashboard elements and add them to your dashboard.
The monitor list dashboard element provides a visual overview of the monitors you specify. It offers a quick glance into important developments about the monitors such as their status and history.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create an empty dashboard](/dashboards/create).
{/* list separator */}
* [Create a monitor](/monitor-data/monitors).
## Create monitor list
1. Go to the Dashboards tab and open the dashboard to which you want to add the monitor list.
2. Click **Add element** in the top right corner.
3. Click **Monitor list** from the list.
4. In **Columns**, select the type of information you want to display for each monitor:
* **Status** displays if the monitor state is normal, triggered, or disabled.
* **History** provides a visual overview of the recent runs of the monitor. Green squares mean normal operation and red squares mean triggered state.
* **Dataset** is the name of the dataset on which the monitor operates.
* **Type** is the type of the monitor.
* **Notifiers** displays the notifiers connected to the monitor.
5. From the list, select the monitors you want to display on the dashboard.
6. Click **Save**.
The new element appears in your dashboard. At the bottom, click **Save** to save your changes to the dashboard.
# Note
This section explains how to create note dashboard elements and add them to your dashboard.
The note dashboard element adds a textbox to your dashboard that you can customise to your needs. For example, you can provide context in a note about the other dashboard elements.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create an empty dashboard](/dashboards/create).
## Create note
1. Go to the Dashboards tab and open the dashboard to which you want to add the note.
2. Click **Add element** in the top right corner.
3. Click **Note** from the list.
4. Enter your text on the left in [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) format. You see the preview of the note dashboard element on the right.
5. Click **Save**.
The new element appears in your dashboard. At the bottom, click **Save** to save your changes to the dashboard.
# Dashboard elements
This section explains how to create different dashboard elements and add them to your dashboard.
Dashboard elements are the different visual elements that you can include in your dashboard to display your data and other information. For example, you can track key metrics, logs, and traces, and monitor real-time data flow.
Choose one of the following to learn more about a dashboard element:
**Add element** in the top right corner.
3. Click **{elementButtonLabel_0}** from the list.
4. Choose one of the following:
* Click **Simple Query Builder** to create your chart using a visual query builder. For more information, see [Create chart using visual query builder](/dashboard-elements/create#create-chart-using-visual-query-builder).
* Click **Advanced Query Language** to create your chart using the Axiom Processing Language (APL). Create a chart in the same way you create a chart in the APL query builder of the [Query tab](/query-data/explore#create-a-query-using-apl).
5. Optional: [Configure the dashboard element](/dashboard-elements/configure).
6. Click **Save**.
The new element appears in your dashboard. At the bottom, click **Save** to save your changes to the dashboard.
## Example with Simple Query Builder
## Example with Advanced Query Language
```kusto
['http-logs']
| summarize count() by status
```
# Scatter plot
This section explains how to create scatter plot dashboard elements and add them to your dashboard.
Scatter plots are used to visualize the correlation or distribution between two distinct metrics or logs. Each point in the scatter plot could represent a log entry, with the X and Y axes showing different log attributes (like request time and response size). The scatter plot chart can be created using the simple query builder or advanced query builder.
For example, plot response size against response time for an API to see if larger responses are correlated with slower response times.
## Example with Simple Query Builder
## Example with Advanced Query Language
```kusto
['sample-http-logs']
| summarize avg(req_duration_ms), avg(resp_header_size_bytes) by resp_body_size_bytes
```
# Statistic
This section explains how to create statistic dashboard elements and add them to your dashboard.
Statistics dashboard elements display a summary of the selected metrics over a given time period. For example, you can use a statistic dashboard element to show the average, sum, min, max, and count of response times or error counts.
## Example with Simple Query Builder
## Example with Advanced Query Language
```kusto
['sample-http-logs']
| summarize avg(resp_body_size_bytes)
```
# Table
This section explains how to create table dashboard elements and add them to your dashboard.
The table dashboard element displays a summary of any attributes from your metrics, logs, or traces in a sortable table format. Each row in the table could represent a different service, host, or other entity, with columns showing various attributes or metrics for that entity.
## Example with Simple Query Builder
## Example with Advanced Query Language
With this option, the table chart type has the capability to display a non-aggregated view of events.
```kusto
['sample-http-logs']
| summarize avg(resp_body_size_bytes) by bin_auto(_time)
```
# Time series
This section explains how to create time series dashboard elements and add them to your dashboard.
Time series charts show the change in your data over time which can help identify infrastructure issues, spikes, or dips in the data. This can be a simple line chart, an area chart, or a bar chart. A time series chart might be used to show the change in the volume of log events, error rates, latency, or other time-sensitive data.
## Example with Simple Query Builder
## Example with Advanced Query Language
```kusto
['sample-http-logs']
| summarize count() by bin_auto(_time)
```
# Configure dashboards
This page explains how to configure your dashboards.
## Select time range
When you select the time range, you specify the time interval for which you want to display data in the dashboard. Changing the time range affects the data displayed in all dashboard elements.
To select the time range:
1. In the top right, click **Time range**.
2. Choose one of the following options:
* Use the **Quick range** items to quickly select popular time ranges.
* Use the **Custom start/end date** fields to select specific times.
## Share dashboards
To specify who can access a dashboard:
1. In the top right, click 
**Share**.
2. Select one of the following:
* Select **Just Me** to make the dashboard private. Only you can access the dashboard.
* Select a group in your Axiom organization. Only members of the selected group can access the dashboard. For more information about groups, see [Access](/reference/settings#access-overview).
* Select **Everyone** to make the dashboard accessible to all users in your Axiom organization.
3. At the bottom, click **Save** to save your changes to the dashboard.
**Annotations**.
2. Select one of the following:
* Show all annotations
* Hide all annotations
* Selective determine the annotations types to display
3. At the bottom, click **Save** to save your changes to the dashboard.
## Set dashboard as homepage
To set a dashboard as the homepage of your browser, click 
**Set as homepage** in the top right.
## Enter full screen
Full-screen mode is useful for displaying the dashboard on a TV or shared monitor.
To enter full-screen mode, click 
**Full screen** in the top right.
# Create dashboards
This section explains how to create and delete dashboards.
To create a dashboard, choose one of the following:
* [Create an empty dashboard](#create-empty-dashboards).
* [Fork an existing dashboard](#fork-dashboards). This is how you make a copy of prebuilt integration dashboards that you cannot directly edit.
* [Duplicate an existing dashboard](#duplicate-dashboards). This is how you make a copy of dashboards other than prebuilt integration dashboards.
After creating a dashboard:
* [Add dashboard elements](/dashboard-elements/create). For example, add a table or a time series chart.
* [Configure the dashboard](/dashboards/configure). For example, control who can access the dashboard and change the time range.
## Create empty dashboards
1. Click the Dashboards tab.
2. In the top right corner, click **New dashboard**.
3. Add a name and a description.
4. Click **Create**.
## Fork dashboards
1. Click the Dashboards tab.
2. Find the dashboard in the list.
3. Click **More**.
4. Click **Fork dashboard**.
Alternatively:
1. Open the dashboard.
2. Click 
**Fork dashboard** in the top right corner.
## Duplicate dashboards
1. Click the Dashboards tab.
2. Find the dashboard in the list.
3. Click **More**.
4. Click **Duplicate dashboard**.
## Delete dashboard
1. Click the Dashboards tab.
2. Find the dashboard in the list.
3. Click **More**.
4. Click **Delete dashboard**.
5. Click **Delete**.
# Dashboards
This section introduces the Dashboards tab and explains how to create your first dashboard.
Dashboards provide a single view into your data.
Axiom provides a mature dashboards experience that allows collections of queries across multiple datasets to be visualized in one place.
Dashboards are easy to share, benefit from collaboration, and bring separate datasets together in a single view.
## Dashboards tab
The Dashboards tab lists the dashboards you have access to.
* The **Integrations** section lists prebuilt dashboards. Axiom automatically built these dashboards as part of the [apps that enrich your Axiom experience](/apps/introduction). The integration dashboards are read-only and you cannot edit them. To create a copy of an integration dashboard that you can edit, [fork the original dashboard](/dashboards/configure#fork-dashboards).
* The sections below list the private and shared dashboards you can access.
To open a dashboard, click a dashboard in the list.
## Work with dashboards
**Settings > Endpoints**.
2. Click **New endpoint**.
3. Click **{endpointName_0}**.
4. Name the endpoint.
5. Select the dataset where you want to send data.
6. Copy the URL displayed for the newly created endpoint. This is the target URL where you send the data.
## Configure Honeycomb
In Honeycomb, specify the following environment variables:
* `APIKey` or `WriteKey` is your Honeycomb API token. For information, see the [Honeycomb documentation](https://docs.honeycomb.io/get-started/configure/environments/manage-api-keys/).
* `APIHost` is the target URL for the endpoint you have generated in Axiom by following the procedure above. For example, `https://opbizplsf8klnw.ingress.axiom.co`.
* `Dataset` is the name of the Axiom dataset where you want to send data.
## Examples
### Send logs from Honeycomb using JavaScript
```js
const Libhoney = require('libhoney');
const hny = new Libhoney({
writeKey: '',
dataset: '',
apiHost: '',
});
hny.sendNow({ message: 'Welcome to Axiom Endpoints!' });
```
### Send logs from Honeycomb using Python
```py
import libhoney
libhoney.init(writekey="", dataset="", api_host="")
event = libhoney.new_event()
event.add_field("foo", "bar")
event.add({"message": "Welcome, to Axiom Endpoints!"})
event.send()
```
### Send logs from Honeycomb using Golang
```go
package main
import (
"github.com/honeycombio/libhoney-go"
)
func main() {
libhoney.Init(libhoney.Config{
WriteKey: "",
Dataset: "",
APIHost: "",
})
defer libhoney.Close() // Flush any pending calls to Honeycomb
var ev = libhoney.NewEvent()
ev.Add(map[string]interface{}{
"duration_ms": 155.67,
"method": "post",
"hostname": "endpoints",
"payload_length": 43,
})
ev.Send()
}
```
# Send data from Loki to Axiom
Integrate Axiom in your existing Loki stack with minimal effort and without breaking any of your existing Loki workflows.
export const endpointName_0 = "Loki"
This page explains how to send data from Loki to Axiom.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
## Configure {endpointName_0} endpoint in Axiom
1. Click **Settings > Endpoints**.
2. Click **New endpoint**.
3. Click **{endpointName_0}**.
4. Name the endpoint.
5. Select the dataset where you want to send data.
6. Copy the URL displayed for the newly created endpoint. This is the target URL where you send the data.
## Configure Loki
In Loki, specify the following environment variables:
* `host` or `url` is the target URL for the endpoint you have generated in Axiom by following the procedure above. For example, `https://opbizplsf8klnw.ingress.axiom.co`.
* Optional: Use `labels` or `tags` to specify labels or tags for your app.
## Examples
### Send logs from Loki using JavaScript
```js
const { createLogger, transports, format, } = require("winston");
const LokiTransport = require("winston-loki");
let logger;
const initializeLogger = () => {
if (logger) {
return;
}
logger = createLogger({
transports: [
new LokiTransport({
host: "$LOKI_ENDPOINT_URL",
labels: { app: "axiom-loki-endpoint" },
json: true,
format: format.json(),
replaceTimestamp: true,
onConnectionError: (err) => console.error(err),
}),
new transports.Console({
format: format.combine(format.simple(), format.colorize()),
}),
],
});
};
initializeLogger()
logger.info("Starting app...");
```
### Send logs from Loki using Python
```py
import logging
import logging_loki
# Create a handler
handler = logging_loki.LokiHandler(
url='$LOKI_ENDPOINT_URL',
tags={'app': 'axiom-loki-py-endpoint'},
version='1',
)
# Create a logger
logger = logging.getLogger('loki')
# Add the handler to the logger
logger.addHandler(handler)
# Log some messages
logger.info('Hello, world from Python!')
logger.warning('This is a warning')
logger.error('This is an error')
```
# Send data from Splunk to Axiom
Integrate Axiom in your existing Splunk app with minimal effort and without breaking any of your existing Splunk stack.
export const endpointName_0 = "Splunk"
This page explains how to send data from Splunk to Axiom.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
## Configure {endpointName_0} endpoint in Axiom
1. Click **Settings > Endpoints**.
2. Click **New endpoint**.
3. Click **{endpointName_0}**.
4. Name the endpoint.
5. Select the dataset where you want to send data.
6. Copy the URL displayed for the newly created endpoint. This is the target URL where you send the data.
## Configure Splunk
In Splunk, specify the following environment variables:
* `token` is your Splunk API token. For information, see the [Splunk documentation](https://docs.splunk.com/observability/en/admin/authentication/authentication-tokens/api-access-tokens.html).
* `url` or `host` is the target URL for the endpoint you have generated in Axiom by following the procedure above. For example, `https://opbizplsf8klnw.ingress.axiom.co`.
## Examples
### Send logs from Splunk using JavaScript
```js
var SplunkLogger = require('splunk-logging').Logger;
var config = {
token: '$SPLUNK_TOKEN',
url: '$AXIOM_ENDPOINT_URL',
};
var Logger = new SplunkLogger({
token: config.token,
url: config.url,
host: '$AXIOM_ENDPOINT_URL',
});
var payload = {
// Message can be anything; doesn’t have to be an object
message: {
temperature: '70F',
chickenCount: 500,
},
};
console.log('Sending payload', payload);
Logger.send(payload, function (err, resp, body) {
// If successful, body will be { text: 'Success', code: 0 }
console.log('Response from Splunk', body);
});
```
### Send logs from Splunk using Python
* Your Splunk deployment `port` and `index` values are required in your Python code.
```py
import logging
from splunk_handler import SplunkHandler
splunk = SplunkHandler(
host="$AXIOM_SPLUNK_ENDPOINT_URL",
port='8088',
token='',
index='main'
)
logging.getLogger('').addHandler(splunk)
logging.warning('Axiom endpoints!')
```
### Send logs from Splunk using Golang
```js
package main
import "github.com/docker/docker/daemon/logger/splunk"
func main() {
// Create new Splunk client
splunk := splunk.NewClient(
nil,
"https://{$AXIOM_SPLUNK_ENDPOINT}:8088/services/collector",
"{your-token}",
"{your-source}",
"{your-sourcetype}",
"{your-index}"
)
err := splunk.Log(
interface{"msg": "axiom endpoints", "msg2": "endpoints"}
)
if err != nil {
return err
}
err = splunk.LogWithTime(
time.Now(),
interface{"msg": "axiom endpoints", "msg2": "endpoints"}
)
if err != nil {
return err
}
```
# Frequently Asked Questions
Learn more about Axiom.
This page aims to offer a deeper understanding of Axiom. If you can’t find an answer to your questions, please feel free to [contact our team](https://axiom.co/contact).
## What is Axiom?
Axiom is a log management and analytics solution that reduces the cost and management overhead of logging as much data as you want.
With Axiom, organizations no longer need to choose between their data and their costs. Axiom has been built from the ground-up to allow for highly efficient data ingestion and storage, and then a zero-to-infinite query scaling that allows you to query all your data, all the time.
Organizations use Axiom for continuous monitoring and observability, as well as an event store for running analytics and deriving insights from all their event data.
Axiom consists of a datastore and a user-experience that work in tandem to provide a completely unique log-management and analytics experience.
## Can I run Axiom in my own cloud/infrastructure?
Axiom enables you to store data in your own storage with the Bring Your Own Bucket (BYOB) feature. You provide your own S3-compatible object storage, and the Axiom control plane handles ingest, query execution, and all other background tasks. This is not an on-premises solution, but it enables you to maintain control over your data at rest.
Using Axiom as a cloud SaaS product without the BYOB option is safe, affordable, and the best choice for most use cases. Billed month-to-month on our [Team plan](https://axiom.co/pricing) for ingest workloads up to 50TB/mo, and with no upper limit on our annual [Enterprise plan](https://axiom.co/pricing), Axiom supports tens of thousands of organizations today. However, if you are a large enterprise customer and your organization requires data sovereignty for compliance reasons or secondary workloads, using Axiom with the BYOB premium option is the answer.
Axiom BYOB is available exclusively on our annual [Enterprise plan](https://axiom.co/pricing).
## How is Axiom different than other logging solutions?
At Axiom, our goal is that no organization has to ignore or delete a single piece of data no matter its source: logs, events, frontend, backends, audits, etc.
We found that existing solutions would place restrictions on how much data can be collected either on purpose or as a side-effect of their architectures.
For example, state of the art in logging is running stateful clusters that need shared knowledge of ingestion and will use a mixture of local SSD-based storage and remote object storage.
### Side-effects of legacy vendors
1. There is a non-trivial cost in increasing your data ingest as clusters need to be scaled and more SSD storage and IOPs need to be provided
2. The choice needs to be made between hot and cold data, and also what is archived. Now your data is in 2-3 different places and queries can be fast or slow depending on where the data is
The end result is needing to carefully consider all data that is ingested, and putting limits and/or sampling to control the DevOps and cost burden.
### The ways Axiom is different
1. Decoupled ingest and querying pipelines
2. Stateless ingest pipeline that requires minimal compute/memory to storage as much as 1.5TB/day per vCPU
3. Ingests all data into object storage, enabling the cheapest storage possible for all ingested data
4. Enables querying scale-out with cloud functions, requiring no constantly-running servers waiting for a query to be processed. Instead, enjoy zero-to-infinity querying instantly
### The benefits of Axiom’s approach
1. The most efficient ingestion pipeline for massive amounts of data
2. Store more data for less by exclusively using inexpensive object storage for all data
3. Query data that’s 10 milliseconds or 10 years old at any time
4. Reduce the total cost of ownership of your log management and analytics pipelines with simple scale and maintenance that Axiom provides
5. Free your organization to do more with it’s data
## How long can I retain data for with Axiom?
Axiom’s free forever [Personal plan](https://axiom.co/pricing) provides a generous 30 days of retention.
Axiom’s [Team plan](https://axiom.co/pricing) provides 95 days of retention, ensuring a complete picture of your data for over 3 months.
Retention on Axiom’s [Enterprise plan](https://axiom.co/pricing) can be customised to your needs, with the option for unlimited retention so your organization has access to all its data, all the time.
## Can I try Axiom for free?
Yes. Axiom’s [Personal plan](https://axiom.co/pricing) is free forever with a generous allowance, and is available to all customers.
With unlimited users included, Axiom’s [Team plan](https://axiom.co/pricing) starting at \$25/mo is a great choice for growing companies, and for Enterprise organizations who want to run a proof-of-concept.
## How is Axiom licensed?
Axiom’s [Team plan](https://axiom.co/pricing) is billed on a monthly basis.
Axiom’s [Enterprise plan](https://axiom.co/pricing) is billed on an annual basis, with license details tailored to your organization’s needs.
# Get started
This guide introduces you to the concepts behind working with Axiom and give a short introduction to each of the high-level features.
## 1. Send your data to Axiom
You can send data to Axiom in a variety of ways. Each individual piece of data is an event.
Events can be emitted from internal or third-party services, cloud functions, containers, virtual machines (VMs), or even scripts. Events follow the [JSON specification](https://www.json.org/json-en.html) for which field types are supported, an event could look like this:
```json
{
"service": "api-http",
"severity": "error",
"duration": 231,
"customer_id": "ghj34g32poiu4",
"tags": ["aws-east-1", "zone-b"],
"metadata": {
"version": "3.1.2"
}
}
```
An event must belong to a dataset which is a collection of similar events. You can have multiple datasets that help to segment your events to make them easier to query and visualize, and also aide in access control.
Axiom stores every event you send and makes it available to you for querying either by streaming logs in real-time, or by analyzing events to produce visualizations.
The underlying data store of Axiom is a time series database. This means every event is indexed with a timestamp specified at ingress or set automatically.
Axiom doesn’t sample your data on ingest or querying, unless you’ve expressly instructed it to.
* Click your app’s name to view its details. Within the app’s page, select the triggers tab to review the triggers associated with your app.
* Under the routes section of the triggers tab, you will find the URL route assigned to your Worker. This is where your Cloudflare Worker responds to incoming requests. Vist the [Cloudflare Workers documentation](https://developers.cloudflare.com/workers/get-started/guide/) to learn how to configure routes
## Observe the telemetry data in Axiom
As you interact with your app, traces will be collected and exported to Axiom, allowing you to monitor, analyze, and gain insights into your app’s performance and behavior.
## Dynamic OpenTelemetry traces dashboard
This data can then be further viewed and analyzed in Axiom’s dashboard, offering a deeper understanding of your app’s performance and behavior.
**Working with Cloudflare Pages Functions:** Integration with OpenTelemetry is similar to Workers but uses the Cloudflare Dashboard for configuration, bypassing **`wrangler.toml`**. This simplifies setup through the Cloudflare dashboard web interface.
## Manual Instrumentation
Manual instrumentation requires adding code into your Worker’s script to create and manage spans around the code blocks you want to trace.
1. Initialize Tracer:
Use the OpenTelemetry API to create a tracer instance at the beginning of your script using the **`@microlabs/otel-cf-workers`** package.
```js
import { trace } from '@opentelemetry/api';
const tracer = trace.getTracer('your-service-name');
```
2. Create start and end Spans:
Manually start spans before the operations or events you want to trace and ensure you end them afterward to complete the tracing lifecycle.
```js
const span = tracer.startSpan('operationName');
try {
// Your operation code here
} finally {
span.end();
}
```
3. Annotate Spans:
Add important metadata to spans to provide additional context. This can include setting attributes or adding events within the span.
```js
span.setAttribute('key', 'value');
span.addEvent('eventName', { 'eventAttribute': 'value' });
```
## Automatic Instrumentation
Automatic instrumentation uses the **`@microlabs/otel-cf-workers`** package to automatically trace incoming requests and outbound fetch calls without manual span management.
1. Instrument your Worker:
Wrap your Cloudflare Workers script with the `instrument` function from the **`@microlabs/otel-cf-workers`** package. This automatically instruments incoming requests and outbound fetch calls.
```js
import { instrument } from '@microlabs/otel-cf-workers';
export default instrument(yourHandler, yourConfig);
```
2. Configuration: Provide configuration details, including how to export telemetry data and service metadata to Axiom as part of the `instrument` function call.
```js
const config = (env) => ({
exporter: {
url: 'https://api.axiom.co/v1/traces',
headers: {
'Authorization': `Bearer ${env.AXIOM_API_TOKEN}`,
'X-Axiom-Dataset': `${env.AXIOM_DATASET}`
},
},
service: { name: 'axiom-cloudflare-workers' },
});
```
After instrumenting your Worker script, the `@microlabs/otel-cf-workers` package takes care of tracing automatically.
## Reference
### List of OpenTelemetry trace fields
| Field Category | Field Name | Description |
| ---------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Unique Identifiers** | | |
| | \_rowid | Unique identifier for each row in the trace data. |
| | span\_id | Unique identifier for the span within the trace. |
| | trace\_id | Unique identifier for the entire trace. |
| **Timestamps** | | |
| | \_systime | System timestamp when the trace data was recorded. |
| | \_time | Timestamp when the actual event being traced occurred. |
| **HTTP Attributes** | | |
| | attributes.custom\["http.host"] | Host information where the HTTP request was sent. |
| | attributes.custom\["http.server\_name"] | Server name for the HTTP request. |
| | attributes.http.flavor | HTTP protocol version used. |
| | attributes.http.method | HTTP method used for the request. |
| | attributes.http.route | Route accessed during the HTTP request. |
| | attributes.http.scheme | Protocol scheme (HTTP/HTTPS). |
| | attributes.http.status\_code | HTTP response status code. |
| | attributes.http.target | Specific target of the HTTP request. |
| | attributes.http.user\_agent | User agent string of the client. |
| | attributes.custom.user\_agent.original | Original user agent string, providing client software and OS. |
| | attributes.custom\["http.accepts"] | Accepted content types for the HTTP request. |
| | attributes.custom\["http.mime\_type"] | MIME type of the HTTP response. |
| | attributes.custom.http.wrote\_bytes | Number of bytes written in the HTTP response. |
| | attributes.http.request.method | HTTP request method used. |
| | attributes.http.response.status\_code | HTTP status code returned in response. |
| **Network Attributes** | | |
| | attributes.net.host.port | Port number on the host receiving the request. |
| | attributes.net.peer.port | Port number on the peer (client) side. |
| | attributes.custom\["net.peer.ip"] | IP address of the peer in the network interaction. |
| | attributes.net.sock.peer.addr | Socket peer address, indicating the IP version used. |
| | attributes.net.sock.peer.port | Socket peer port number. |
| | attributes.custom.net.protocol.version | Protocol version used in the network interaction. |
| | attributes.network.protocol.name | Name of the network protocol used. |
| | attributes.network.protocol.version | Version of the network protocol used. |
| | attributes.server.address | Address of the server handling the request. |
| | attributes.url.full | Full URL accessed in the request. |
| | attributes.url.path | Path component of the URL accessed. |
| | attributes.url.query | Query component of the URL accessed. |
| | attributes.url.scheme | Scheme component of the URL accessed. |
| **Operational Details** | | |
| | duration | Time taken for the operation. |
| | kind | Type of span (for example,, server, client). |
| | name | Name of the span. |
| | scope | Instrumentation scope. |
| | scope.name | Name of the scope for the operation. |
| | service.name | Name of the service generating the trace. |
| | service.version | Version of the service generating the trace. |
| **Resource Attributes** | | |
| | resource.environment | Environment where the trace was captured, for example,, production. |
| | resource.cloud.platform | Platform of the cloud provider, for example,, cloudflare.workers. |
| | resource.cloud.provider | Name of the cloud provider, for example,, cloudflare. |
| | resource.cloud.region | Cloud region where the service is located, for example,, earth. |
| | resource.faas.max\_memory | Maximum memory allocated for the function as a service (FaaS). |
| **Telemetry SDK Attributes** | | |
| | telemetry.sdk.language | Language of the telemetry SDK, for example,, js. |
| | telemetry.sdk.name | Name of the telemetry SDK, for example,, @microlabs/otel-workers-sdk. |
| | telemetry.sdk.version | Version of the telemetry SDK. |
| **Custom Attributes** | | |
| | attributes.custom.greeting | Custom greeting message, for example,, "Welcome to Axiom Cloudflare instrumentation." |
| | attributes.custom\["http.accepts"] | Specifies acceptable response formats for HTTP request. |
| | attributes.custom\["net.asn"] | Autonomous System Number representing the hosting entity. |
| | attributes.custom\["net.colo"] | Colocation center where the request was processed. |
| | attributes.custom\["net.country"] | Country where the request was processed. |
| | attributes.custom\["net.request\_priority"] | Priority of the request processing. |
| | attributes.custom\["net.tcp\_rtt"] | Round Trip Time of the TCP connection. |
| | attributes.custom\["net.tls\_cipher"] | TLS cipher suite used for the connection. |
| | attributes.custom\["net.tls\_version"] | Version of the TLS protocol used for the connection. |
| | attributes.faas.coldstart | Indicates if the function execution was a cold start. |
| | attributes.faas.invocation\_id | Unique identifier for the function invocation. |
| | attributes.faas.trigger | Trigger that initiated the function execution. |
### List of imported libraries
**`@microlabs/otel-cf-workers`**
This package is designed for integrating OpenTelemetry within Cloudflare Workers. It provides automatic instrumentation capabilities, making it easier to collect telemetry data from your Workers apps without extensive manual instrumentation. This package simplifies tracing HTTP requests and other asynchronous operations within Workers.
**`@opentelemetry/api`**
The core API for OpenTelemetry in JavaScript, providing the necessary interfaces and utilities for tracing, metrics, and context propagation. In the context of Cloudflare Workers, it allows developers to manually instrument custom spans, manipulate context, and access the active span if needed.
**`@opentelemetry/exporter-trace-otlp-http`**
This exporter enables your Cloudflare Workers app to send trace data over HTTP to any backend that supports the OTLP (OpenTelemetry Protocol), such as Axiom. Using OTLP ensures compatibility with a wide range of observability tools and standardizes the data export process.
**`@opentelemetry/otlp-exporter-base`**, **`@opentelemetry/otlp-transformer`**
These packages provide the foundational elements for OTLP exporters, including the transformation of telemetry data into the OTLP format and base classes for implementing OTLP exporters. They are important for ensuring that the data exported from Cloudflare Workers adheres to the OTLP specification.
**`@opentelemetry/resources`**
Defines the Resource, which represents the entity producing telemetry. In Cloudflare Workers, Resources can be used to describe the worker (for example,, service name, version) and are attached to all exported telemetry, aiding in identifying data in backend systems.
# Send OpenTelemetry data from a Django app to Axiom
This guide explains how to send OpenTelemetry data from a Django app to Axiom using the Python OpenTelemetry SDK.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
{/* list separator */}
* [Install Python version 3.7 or higher](https://www.python.org/downloads/).
## Install required dependencies
Install the necessary Python dependencies by running the following command in your terminal:
```bash
pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
```
Alternatively, you can add these dependencies to your `requirements.txt` file:
```bash
django
opentelemetry-api
opentelemetry-sdk
opentelemetry-exporter-otlp-proto-http
opentelemetry-instrumentation-django
```
Then, install them using the command:
```bash
pip install -r requirements.txt
```
## Get started with a Django project
1. Create a new Django project if you don’t have one already:
```bash
django-admin startproject your_project_name
```
2. Go to your project directory:
```bash
cd your_project_name
```
3. Create a Django app:
```bash
python manage.py startapp your_app_name
```
## Set up OpenTelemetry Tracing
### Update `manage.py` to initialize tracing
This code initializes OpenTelemetry instrumentation for Django when the project is run. Adding `DjangoInstrumentor().instrument()` ensures that all incoming HTTP requests are automatically traced, which helps in monitoring the app’s performance and behavior without manually adding trace points in every view.
```py
# manage.py
#!/usr/bin/env python
import os
import sys
from opentelemetry.instrumentation.django import DjangoInstrumentor
def main():
"""Run administrative tasks."""
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project_name.settings')
# Initialize OpenTelemetry instrumentation
DjangoInstrumentor().instrument()
try:
from django.core.management import execute_from_command_line
except ImportError as exc:
raise ImportError(
"Couldn't import Django. Are you sure it's installed and "
"available on your PYTHONPATH environment variable? Did you "
"forget to activate a virtual environment?"
) from exc
execute_from_command_line(sys.argv)
if __name__ == '__main__':
main()
```
### Create `exporter.py` for tracer configuration
This file configures the OpenTelemetry tracing provider and exporter. By setting up a `TracerProvider` and configuring the `OTLPSpanExporter`, you define how and where the trace data is sent. The `BatchSpanProcessor` is used to batch and send trace spans efficiently. The tracer created at the end is used throughout the app to create new spans.
```py
# exporter.py
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
# Define the service name resource
resource = Resource(attributes={
SERVICE_NAME: "your-service-name" # Replace with your actual service name
})
# Create a TracerProvider with the defined resource
provider = TracerProvider(resource=resource)
# Configure the OTLP/HTTP Span Exporter with necessary headers and endpoint
otlp_exporter = OTLPSpanExporter(
endpoint="https://api.axiom.co/v1/traces",
headers={
"Authorization": "Bearer YOUR_API_TOKEN", # Replace with your actual API token
"X-Axiom-Dataset": "YOUR_DATASET_NAME" # Replace with your dataset name
}
)
# Create a BatchSpanProcessor with the OTLP exporter
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
# Set the TracerProvider as the global tracer provider
trace.set_tracer_provider(provider)
# Define a tracer for external use
tracer = trace.get_tracer("your-service-name")
```
### Use the tracer in your views
In this step, modify the Django views to use the tracer defined in `exporter.py`. By wrapping the view logic within `tracer.start_as_current_span`, you create spans that capture the execution of these views. This provides detailed insights into the performance of individual request handlers, helping to identify slow operations or errors.
```py
# views.py
from django.http import HttpResponse
from .exporter import tracer # Import the tracer
def roll_dice(request):
with tracer.start_as_current_span("roll_dice_span"):
# Your logic here
return HttpResponse("Dice rolled!")
def home(request):
with tracer.start_as_current_span("home_span"):
return HttpResponse("Welcome to the homepage!")
```
### Update `settings.py` for OpenTelemetry instrumentation
In your Django project’s `settings.py`, add the OpenTelemetry Django instrumentation. This setup automatically creates spans for HTTP requests handled by Django:
```py
# settings.py
from pathlib import Path
from opentelemetry.instrumentation.django import DjangoInstrumentor
DjangoInstrumentor().instrument()
# Build paths inside the project like this: BASE_DIR / 'subdir'.
BASE_DIR = Path(__file__).resolve().parent.parent
```
### Update the app’s urls.py to include the views
Include your views in the URL routing by updating [`urls.py`](http://urls.py) Updating `urls.py` with these entries sets up the URL routing for the Django app. It connects the URL paths to the corresponding view functions. This ensures that when users visit the specified paths, the corresponding views are executed, and their spans are created and sent to Axiom for monitoring.
```python
# urls.py
from django.urls import path
from .views import roll_dice, home
urlpatterns = [
path('', home, name='home'),
path('rolldice/', roll_dice, name='roll_dice'),
]
```
## Run the project
Run the command to start the Django project:
```bash
python3 manage.py runserver
```
In your browser, go to `http://127.0.0.1:8000/rolldice` to interact with your Django app. Each time you load the page, the app displays a message and sends the collected traces to Axiom.
## Send data from an existing Django project
### Manual instrumentation
Manual instrumentation in Python with OpenTelemetry involves adding code to create and manage spans around the blocks of code you want to trace. This approach allows for precise control over the trace data.
1. Install necessary OpenTelemetry packages to enable manual tracing capabilities in your Django app.
```py
pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
```
2. Set up OpenTelemetry in your Django project to manually trace app activities.
```py
# otel_config.py
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
def configure_opentelemetry():
resource = Resource(attributes={"service.name": "your-django-app"})
trace.set_tracer_provider(TracerProvider(resource=resource))
otlp_exporter = OTLPSpanExporter(
endpoint="https://api.axiom.co/v1/traces",
headers={"Authorization": "Bearer YOUR_API_TOKEN", "X-Axiom-Dataset": "YOUR_DATASET_NAME"}
)
span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
return trace.get_tracer(__name__)
tracer = configure_opentelemetry()
```
3. Configure OpenTelemetry to your Django settings to capture telemetry data upon app startup.
```py
# settings.py
from otel_config import configure_opentelemetry
configure_opentelemetry()
```
4. Manually instrument views to create custom spans that trace specific operations within your Django app.
```py
# views.py
from django.http import HttpResponse
from otel_config import tracer
def home_view(request):
with tracer.start_as_current_span("home_view") as span:
span.set_attribute("http.method", request.method)
span.set_attribute("http.url", request.build_absolute_uri())
response = HttpResponse("Welcome to the home page!")
span.set_attribute("http.status_code", response.status_code)
return response
```
5. Apply manual tracing to database operations by wrapping database cursor executions with OpenTelemetry spans.
```py
# db_tracing.py
from django.db import connections
from otel_config import tracer
class TracingCursorWrapper:
def __init__(self, cursor):
self.cursor = cursor
def execute(self, sql, params=None):
with tracer.start_as_current_span("database_query") as span:
span.set_attribute("db.statement", sql)
span.set_attribute("db.type", "sql")
return self.cursor.execute(sql, params)
def __getattr__(self, attr):
return getattr(self.cursor, attr)
def patch_database():
for connection in connections.all():
connection.cursor_wrapper = TracingCursorWrapper
# settings.py
from db_tracing import patch_database
patch_database()
```
### Automatic instrumentation
Automatic instrumentation in Django with OpenTelemetry simplifies the process of adding telemetry data to your app. It uses pre-built libraries that automatically instrument the frameworks and libraries.
1. Install required packages that support automatic instrumentation.
```bash
pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
```
2. Automatically configure OpenTelemetry to trace Django app operations without manual span management.
```py
# otel_config.py
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.django import DjangoInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
def configure_opentelemetry():
resource = Resource(attributes={"service.name": "your-django-app"})
trace.set_tracer_provider(TracerProvider(resource=resource))
otlp_exporter = OTLPSpanExporter(
endpoint="https://api.axiom.co/v1/traces",
headers={"Authorization": "Bearer YOUR_API_TOKEN", "X-Axiom-Dataset": "YOUR_DATASET_NAME"}
)
span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
DjangoInstrumentor().instrument()
```
3. Initialize OpenTelemetry in Django to capture telemetry data from all HTTP requests automatically.
```py
# settings.py
from otel_config import configure_opentelemetry
configure_opentelemetry()
```
4. Update `manage.py` to include OpenTelemetry initialization, ensuring that tracing is active before the Django app fully starts.
```py
#!/usr/bin/env python
import os
import sys
def main():
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project.settings')
from otel_config import configure_opentelemetry
configure_opentelemetry()
try:
from django.core.management import execute_from_command_line
except ImportError as exc:
raise ImportError("Couldn't import Django.") from exc
execute_from_command_line(sys.argv)
if __name__ == '__main__':
main()
```
5. (Optional) Combine automatic and custom manual spans in Django views to enhance trace details for specific complex operations.
```py
# views.py
from opentelemetry import trace
tracer = trace.get_tracer(__name__)
def complex_view(request):
with tracer.start_as_current_span("complex_operation"):
result = perform_complex_operation()
return HttpResponse(result)
```
## Reference
### List of OpenTelemetry trace fields
| Field Category | Field Name | Description |
| ------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| General Trace Information | | |
| | \_rowId | Unique identifier for each row in the trace data. |
| | \_sysTime | System timestamp when the trace data was recorded. |
| | \_time | Timestamp when the actual event being traced occurred. |
| | trace\_id | Unique identifier for the entire trace. |
| | span\_id | Unique identifier for the span within the trace. |
| | parent\_span\_id | Unique identifier for the parent span within the trace. |
| HTTP Attributes | | |
| | attributes.http.method | HTTP method used for the request. |
| | attributes.http.status\_code | HTTP status code returned in response. |
| | attributes.http.route | Route accessed during the HTTP request. |
| | attributes.http.scheme | Protocol scheme (HTTP/HTTPS). |
| | attributes.http.url | Full URL accessed during the HTTP request. |
| User Agent | | |
| | attributes.http.user\_agent | User agent string, providing client software and OS. |
| Custom Attributes | | |
| | attributes.custom\["http.host"] | Host information where the HTTP request was sent. |
| | attributes.custom\["http.server\_name"] | Server name for the HTTP request. |
| | attributes.custom\["net.peer.ip"] | IP address of the peer in the network interaction. |
| Network Attributes | | |
| | attributes.net.host.port | Port number on the host receiving the request. |
| Operational Details | | |
| | duration | Time taken for the operation, typically in microseconds or milliseconds. |
| | kind | Type of span (For example, server, internal). |
| | name | Name of the span, often a high-level title for the operation. |
| Scope and Instrumentation | | |
| | scope | Instrumentation scope, (For example., opentelemetry.instrumentation.django.) |
| Service Attributes | | |
| | service.name | Name of the service generating the trace, typically set as the app or service name. |
| Telemetry SDK Attributes | | |
| | telemetry.sdk.language | Programming language of the SDK used for telemetry, typically 'python' for Django. |
| | telemetry.sdk.name | Name of the telemetry SDK, for example., OpenTelemetry. |
| | telemetry.sdk.version | Version of the telemetry SDK used in the tracing setup. |
### List of imported libraries
The `exporter.py` file and other relevant parts of the Django OpenTelemetry setup import the following libraries:
### `exporter.py`
This module creates and manages trace data in your app. It creates spans and tracers which track the execution flow and performance of your app.
```py
from opentelemetry import trace
```
TracerProvider acts as a container for the configuration of your app’s tracing behavior. It allows you to define how spans are generated and processed, essentially serving as the central point for managing trace creation and propagation in your app.
```py
from opentelemetry.sdk.trace import TracerProvider
```
BatchSpanProcessor is responsible for batching spans before they’re exported. This is an important aspect of efficient trace data management as it aggregates multiple spans into fewer network requests, reducing the overhead on your app’s performance and the tracing backend.
```py
from opentelemetry.sdk.trace.export import BatchSpanProcessor
```
The Resource class is used to describe your app’s service attributes, such as its name, version, and environment. This contextual information is attached to the traces and helps in identifying and categorizing trace data, making it easier to filter and analyze in your monitoring setup.
```py
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
```
The OTLPSpanExporter is responsible for sending your app’s trace data to a backend that supports the OTLP such as Axiom. It formats the trace data according to the OTLP standards and transmits it over HTTP, ensuring compatibility and standardization in how telemetry data is sent across different systems and services.
```py
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
```
### `manage.py`
The DjangoInstrumentor module is used to automatically instrument Django applications. It integrates OpenTelemetry with Django, enabling automatic creation of spans for incoming HTTP requests handled by Django, and simplifying the process of adding telemetry to your app.
```py
from opentelemetry.instrumentation.django import DjangoInstrumentor
```
### `views.py`
This import brings in the tracer instance defined in `exporter.py`, which is used to create spans for tracing the execution of Django views. By wrapping view logic within `tracer.start_as_current_span`, it captures detailed insights into the performance of individual request handlers.
```py
from .exporter import tracer
```
# OpenTelemetry using .NET
This guide explains how to configure a .NET app using the .NET OpenTelemetry SDK to send telemetry data to Axiom.
OpenTelemetry provides a [unified approach to collecting telemetry data](https://opentelemetry.io/docs/languages/net/) from your .NET applications. This guide explains how to configure OpenTelemetry in a .NET application to send telemetry data to Axiom using the OpenTelemetry SDK.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/).
* [Create a dataset](/reference/settings#data) where you want to send data.
* [Create an API token in Axiom with permissions to ingest and query data](/reference/tokens).
* Install the .NET 6.0 SDK on your development machine.
* Use your existing .NET application or start with the sample provided in the `program.cs` below.
## Install dependencies
Run the following command in your terminal to install the necessary NuGet packages:
```bash
dotnet add package OpenTelemetry --version 1.7.0
dotnet add package OpenTelemetry.Exporter.Console --version 1.7.0
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol --version 1.7.0
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.7.0
dotnet add package OpenTelemetry.Instrumentation.AspNetCore --version 1.7.1
dotnet add package OpenTelemetry.Instrumentation.Http --version 1.6.0-rc.1
```
Replace the `dotnet.csproj` file in your project with the following:
```csharp
## Dynamic OpenTelemetry traces dashboard
This data can then be further viewed and analyzed in Axiom’s dashboard, providing insights into the performance and behavior of your app.
## Send data from an existing Golang project
### Manual Instrumentation
Manual instrumentation in Go involves managing spans within your code to track operations and events. This method offers precise control over what is instrumented and how spans are configured.
1. Initialize the tracer:
Use the OpenTelemetry API to obtain a tracer instance. This tracer will be used to start and manage spans.
```go
tracer := otel.Tracer("serviceName")
```
2. Create and manage spans:
Manually start spans before the operations you want to trace and ensure they are ended after the operations complete.
```go
ctx, span := tracer.Start(context.Background(), "operationName")
defer span.End()
// Perform the operation here
```
3. Annotate spans:
Enhance spans with additional information using attributes or events to provide more context about the traced operation.
```go
span.SetAttributes(attribute.String("key", "value"))
span.AddEvent("eventName", trace.WithAttributes(attribute.String("key", "value")))
```
### Automatic Instrumentation
Automatic instrumentation in Go uses libraries and integrations that automatically create spans for operations, simplifying the addition of observability to your app.
1. Instrumentation libraries:
Use `OpenTelemetry-contrib` libraries designed for automatic instrumentation of standard Go frameworks and libraries, such as `net/http`.
```go
import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
```
2. Wrap handlers and clients:
Automatically instrument HTTP servers and clients by wrapping them with OpenTelemetry’s instrumentation. For HTTP servers, wrap your handlers with `otelhttp.NewHandler`.
```go
http.Handle("/path", otelhttp.NewHandler(handler, "operationName"))
```
3. Minimal code changes:
After setting up automatic instrumentation, no further changes are required for tracing standard operations. The instrumentation takes care of starting, managing, and ending spans.
## Reference
### List of OpenTelemetry trace fields
| Field Category | Field Name | Description |
| ---------------------------- | --------------------------------------- | ------------------------------------------------------------------- |
| **Unique Identifiers** | | |
| | \_rowid | Unique identifier for each row in the trace data. |
| | span\_id | Unique identifier for the span within the trace. |
| | trace\_id | Unique identifier for the entire trace. |
| **Timestamps** | | |
| | \_systime | System timestamp when the trace data was recorded. |
| | \_time | Timestamp when the actual event being traced occurred. |
| **HTTP Attributes** | | |
| | attributes.custom\["http.host"] | Host information where the HTTP request was sent. |
| | attributes.custom\["http.server\_name"] | Server name for the HTTP request. |
| | attributes.http.flavor | HTTP protocol version used. |
| | attributes.http.method | HTTP method used for the request. |
| | attributes.http.route | Route accessed during the HTTP request. |
| | attributes.http.scheme | Protocol scheme (HTTP/HTTPS). |
| | attributes.http.status\_code | HTTP response status code. |
| | attributes.http.target | Specific target of the HTTP request. |
| | attributes.http.user\_agent | User agent string of the client. |
| | attributes.custom.user\_agent.original | Original user agent string, providing client software and OS. |
| **Network Attributes** | | |
| | attributes.net.host.port | Port number on the host receiving the request. |
| | attributes.net.peer.port | Port number on the peer (client) side. |
| | attributes.custom\["net.peer.ip"] | IP address of the peer in the network interaction. |
| | attributes.net.sock.peer.addr | Socket peer address, indicating the IP version used. |
| | attributes.net.sock.peer.port | Socket peer port number. |
| | attributes.custom.net.protocol.version | Protocol version used in the network interaction. |
| **Operational Details** | | |
| | duration | Time taken for the operation. |
| | kind | Type of span (for example,, server, client). |
| | name | Name of the span. |
| | scope | Instrumentation scope. |
| | service.name | Name of the service generating the trace. |
| | service.version | Version of the service generating the trace. |
| **Resource Attributes** | | |
| | resource.environment | Environment where the trace was captured, for example,, production. |
| | attributes.custom.http.wrote\_bytes | Number of bytes written in the HTTP response. |
| **Telemetry SDK Attributes** | | |
| | telemetry.sdk.language | Language of the telemetry SDK (if previously not included). |
| | telemetry.sdk.name | Name of the telemetry SDK (if previously not included). |
| | telemetry.sdk.version | Version of the telemetry SDK (if previously not included). |
### List of imported libraries
### OpenTelemetry Go SDK
**`go.opentelemetry.io/otel`**
This is the core SDK for OpenTelemetry in Go. It provides the necessary tools to create and manage telemetry data (traces, metrics, and logs).
### OTLP Trace Exporter
**`go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`**
This package allows your app to export telemetry data over HTTP using the OpenTelemetry Protocol (OTLP). It’s important for sending data to Axiom or any other backend that supports OTLP.
### Resource and Trace Packages
**`go.opentelemetry.io/otel/sdk/resource`** and **`go.opentelemetry.io/otel/sdk/trace`**
These packages help define the properties of your telemetry data, such as service name and version, and manage trace data within your app.
### Semantic Conventions
**`go.opentelemetry.io/otel/semconv/v1.24.0`**
This package provides standardized schema URLs and attributes, ensuring consistency across different OpenTelemetry implementations.
### Tracing API
**`go.opentelemetry.io/otel/trace`**
This package offers the API for tracing. It enables you to create spans, record events, and manage context propagation in your app.
### HTTP Instrumentation
**`go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp`**
Used for instrumenting HTTP clients and servers. It automatically records data about HTTP requests and responses, which is essential for web apps.
### Propagators
**`go.opentelemetry.io/otel/propagation`**
This package provides the ability to propagate context and trace information across service boundaries.
# Send data from Java app using OpenTelemetry
This page explains how to configure a Java app using the Java OpenTelemetry SDK to send telemetry data to Axiom.
OpenTelemetry provides a unified approach to collecting telemetry data from your Java applications. This page demonstrates how to configure OpenTelemetry in a Java app to send telemetry data to Axiom using the OpenTelemetry SDK.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
{/* list separator */}
* [Install JDK 11](https://www.oracle.com/java/technologies/java-se-glance.html) or later
* [Install Maven](https://maven.apache.org/download.cgi)
* Use your own app written in Java or the provided `DiceRollerApp.java` sample.
## Create project
To create a Java project, run the Maven archetype command in the terminal:
```bash
mvn archetype:generate -DgroupId=com.example -DartifactId=MyProject -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
This command creates a new project in a directory named `MyProject` with a standard directory structure.
## Create core app
`DiceRollerApp.java` is the core of the sample app. It simulates rolling a dice and demonstrates the usage of OpenTelemetry for tracing. The app includes two methods: one for a simple dice roll and another that demonstrates the usage of span links to establish relationships between spans across different traces.
Create the `DiceRollerApp.java` in the `src/main/java/com/example` directory with the following content:
```java
package com.example;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
import java.util.Random;
public class DiceRollerApp {
private static final Tracer tracer;
static {
OpenTelemetry openTelemetry = OtelConfiguration.initializeOpenTelemetry();
tracer = openTelemetry.getTracer(DiceRollerApp.class.getName());
}
public static void main(String[] args) {
rollDice();
rollDiceWithLink();
}
private static void rollDice() {
Span span = tracer.spanBuilder("rollDice").startSpan();
try (Scope scope = span.makeCurrent()) {
int roll = 1 + new Random().nextInt(6);
System.out.println("Rolled a dice: " + roll);
} finally {
span.end();
}
}
private static void rollDiceWithLink() {
Span parentSpan = tracer.spanBuilder("rollWithLink").startSpan();
try (Scope parentScope = parentSpan.makeCurrent()) {
Span childSpan = tracer.spanBuilder("rolldice")
.addLink(parentSpan.getSpanContext())
.startSpan();
try (Scope childScope = childSpan.makeCurrent()) {
int roll = 1 + new Random().nextInt(6);
System.out.println("Dice roll result (with link): " + roll);
} finally {
childSpan.end();
}
} finally {
parentSpan.end();
}
}
}
```
## Configure OpenTelemetry
`OtelConfiguration.java` sets up the OpenTelemetry SDK and configures the exporter to send data to Axiom. It initializes the tracer provider, sets up the Axiom exporter, and configures the resource attributes.
Create the `OtelConfiguration.java` file in the `src/main/java/com/example` directory with the following content:
```java
package com.example;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import java.util.concurrent.TimeUnit;
public class OtelConfiguration {
private static final String SERVICE_NAME = "YOUR_SERVICE_NAME";
private static final String SERVICE_VERSION = "YOUR_SERVICE_VERSION";
private static final String OTLP_ENDPOINT = "https://api.axiom.co/v1/traces";
private static final String BEARER_TOKEN = "Bearer API_TOKEN";
private static final String AXIOM_DATASET = "DATASET_NAME";
public static OpenTelemetry initializeOpenTelemetry() {
Resource resource = Resource.getDefault()
.merge(Resource.create(Attributes.of(
AttributeKey.stringKey("service.name"), SERVICE_NAME,
AttributeKey.stringKey("service.version"), SERVICE_VERSION
)));
OtlpHttpSpanExporter spanExporter = OtlpHttpSpanExporter.builder()
.setEndpoint(OTLP_ENDPOINT)
.addHeader("Authorization", BEARER_TOKEN)
.addHeader("X-Axiom-Dataset", AXIOM_DATASET)
.build();
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
.addSpanProcessor(BatchSpanProcessor.builder(spanExporter)
.setScheduleDelay(100, TimeUnit.MILLISECONDS)
.build())
.setResource(resource)
.build();
OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.buildAndRegisterGlobal();
Runtime.getRuntime().addShutdownHook(new Thread(sdkTracerProvider::close));
return openTelemetry;
}
}
```
* Replace `API_TOKEN` with the Axiom API token you have generated. For added security, store the API token in an environment variable.
* Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
## Configure project
The `pom.xml` file defines the project structure and dependencies for Maven. It includes the necessary OpenTelemetry libraries and configures the build process.
Update the `pom.xml` file in the root of your project directory with the following content:
```xml
## Dynamic OpenTelemetry traces dashboard
This data can then be further viewed and analyzed in Axiom’s dashboard, providing insights into the performance and behaviour of your app.
## Send data from an existing Node project
### Manual Instrumentation
Manual instrumentation in Node.js requires adding code to create and manage spans around the code blocks you want to trace.
1. Initialize Tracer:
Import and configure a tracer in your Node.js app. Use the tracer configured in your instrumentation setup (instrumentation.ts).
```js
// Assuming OpenTelemetry SDK is already configured
const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('example-tracer');
```
2. Create Spans:
Wrap the code blocks that you want to trace with spans. Start and end these spans within your code.
```js
const span = tracer.startSpan('operation_name');
try {
// Your code here
span.end();
} catch (error) {
span.recordException(error);
span.end();
}
```
3. Annotate Spans:
Add metadata and logs to your spans for the trace data.
```js
span.setAttribute('key', 'value');
span.addEvent('event name', { eventKey: 'eventValue' });
```
### Automatic Instrumentation
Automatic instrumentation in Node.js simplifies adding telemetry data to your app. It uses pre-built libraries to automatically instrument common frameworks and libraries.
1. Install Instrumentation Libraries:
Use OpenTelemetry packages that automatically instrument common Node.js frameworks and libraries.
```bash
npm install @opentelemetry/auto-instrumentations-node
```
2. Instrument Application:
Configure your app to use these libraries, which will automatically generate spans for standard operations.
```js
// In your instrumentation setup (instrumentation.ts)
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const sdk = new NodeSDK({
// ... other configurations ...
instrumentations: [getNodeAutoInstrumentations()]
});
```
After you set them up, these libraries automatically trace relevant operations without additional code changes in your app.
## Reference
### List of OpenTelemetry trace fields
| Field Category | Field Name | Description |
| ------------------------------- | --------------------------------------- | ------------------------------------------------------------ |
| **Unique Identifiers** | | |
| | \_rowid | Unique identifier for each row in the trace data. |
| | span\_id | Unique identifier for the span within the trace. |
| | trace\_id | Unique identifier for the entire trace. |
| **Timestamps** | | |
| | \_systime | System timestamp when the trace data was recorded. |
| | \_time | Timestamp when the actual event being traced occurred. |
| **HTTP Attributes** | | |
| | attributes.custom\["http.host"] | Host information where the HTTP request was sent. |
| | attributes.custom\["http.server\_name"] | Server name for the HTTP request. |
| | attributes.http.flavor | HTTP protocol version used. |
| | attributes.http.method | HTTP method used for the request. |
| | attributes.http.route | Route accessed during the HTTP request. |
| | attributes.http.scheme | Protocol scheme (HTTP/HTTPS). |
| | attributes.http.status\_code | HTTP response status code. |
| | attributes.http.target | Specific target of the HTTP request. |
| | attributes.http.user\_agent | User agent string of the client. |
| **Network Attributes** | | |
| | attributes.net.host.port | Port number on the host receiving the request. |
| | attributes.net.peer.port | Port number on the peer (client) side. |
| | attributes.custom\["net.peer.ip"] | IP address of the peer in the network interaction. |
| **Operational Details** | | |
| | duration | Time taken for the operation. |
| | kind | Type of span (for example,, server, client). |
| | name | Name of the span. |
| | scope | Instrumentation scope. |
| | service.name | Name of the service generating the trace. |
| **Resource Process Attributes** | | |
| | resource.process.command | Command line string used to start the process. |
| | resource.process.command\_args | List of command line arguments used in starting the process. |
| | resource.process.executable.name | Name of the executable running the process. |
| | resource.process.executable.path | Path to the executable running the process. |
| | resource.process.owner | Owner of the process. |
| | resource.process.pid | Process ID. |
| | resource.process.runtime.description | Description of the runtime environment. |
| | resource.process.runtime.name | Name of the runtime environment. |
| | resource.process.runtime.version | Version of the runtime environment. |
| **Telemetry SDK Attributes** | | |
| | telemetry.sdk.language | Language of the telemetry SDK. |
| | telemetry.sdk.name | Name of the telemetry SDK. |
| | telemetry.sdk.version | Version of the telemetry SDK. |
### List of imported libraries
The `instrumentation.ts` file imports the following libraries:
### **`@opentelemetry/sdk-node`**
This package is the core SDK for OpenTelemetry in Node.js. It provides the primary interface for configuring and initializing OpenTelemetry in a Node.js app. It includes functionalities for managing traces and context propagation. The SDK is designed to be extensible, allowing for custom configurations and integration with different telemetry backends like Axiom.
### **`@opentelemetry/auto-instrumentations-node`**
This package offers automatic instrumentation for Node.js apps. It simplifies the process of instrumenting various common Node.js libraries and frameworks. By using this package, developers can automatically collect telemetry data (such as traces) from their apps without needing to manually instrument each library or API call. This is important for apps with complex dependencies, as it ensures comprehensive and consistent telemetry collection across the app.
### **`@opentelemetry/exporter-trace-otlp-proto`**
The **`@opentelemetry/exporter-trace-otlp-proto`** package provides an exporter that sends trace data using the OpenTelemetry Protocol (OTLP). OTLP is the standard protocol for transmitting telemetry data in the OpenTelemetry ecosystem. This exporter allows Node.js apps to send their collected traces to any backend that supports OTLP, such as Axiom. The use of OTLP ensures broad compatibility and a standardized way of transmitting telemetry data.
### **`@opentelemetry/sdk-trace-base`**
Contained within this package is the **`BatchSpanProcessor`**, among other foundational elements for tracing in OpenTelemetry. The **`BatchSpanProcessor`** is a component that collects and processes spans (individual units of trace data). As the name suggests, it batches these spans before sending them to the configured exporter (in this case, the `OTLPTraceExporter`). This batching mechanism is efficient as it reduces the number of outbound requests by aggregating multiple spans into fewer batches. It helps in the performance and scalability of trace data export in an OpenTelemetry-instrumented app.
# Send OpenTelemetry data from a Python app to Axiom
This guide explains how to send OpenTelemetry data from a Python app to Axiom using the Python OpenTelemetry SDK.
This guide explains how to send OpenTelemetry data from a Python app to Axiom using the [Python OpenTelemetry SDK](https://opentelemetry.io/docs/languages/python/instrumentation/).
## Prerequisites
* Install Python version 3.7 or higher.
* Create an Axiom account. To sign up for a free account, go to the [Axiom app](https://app.axiom.co/).
* Create a dataset in Axiom. This is where the Python app sends telemetry data. For more information, see [Data Settings](/reference/datasets).
* Create an API key in Axiom with permissions to query and ingest data. For more information, see [Access Settings](/reference/tokens).
## Install required dependencies
To install the required Python dependencies, run the following code in your terminal:
```bash
pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-flask opentelemetry-exporter-otlp Flask
```
### Install dependencies with requirements file
Alternatively, if you use a `requirements.txt` file in your Python project, add these lines:
```txt
opentelemetry-api
opentelemetry-sdk
opentelemetry-instrumentation-flask
opentelemetry-exporter-otlp
Flask
```
Then run the following code in your terminal to install dependencies:
```bash
pip install -r requirements.txt
```
## Create an app.py file
Create an `app.py` file with the following content. This file creates a basic HTTP server using Flask. It also demonstrates the usage of span links to establish relationships between spans across different traces.
```python
# app.py
from flask import Flask
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry import trace
from random import randint
import exporter
# Creating a Flask app instance
app = Flask(__name__)
# Automatically instruments Flask app to enable tracing
FlaskInstrumentor().instrument_app(app)
# Retrieving a tracer from the custom exporter
tracer = exporter.service1_tracer
@app.route("/rolldice")
def roll_dice(parent_span=None):
# Starting a new span for the dice roll. If a parent span is provided, link to its span context.
with tracer.start_as_current_span("roll_dice_span",
links=[trace.Link(parent_span.get_span_context())] if parent_span else None) as span:
# Spans can be created with zero or more Links to other Spans that are related.
# Links allow creating connections between different traces
return str(roll())
@app.route("/roll_with_link")
def roll_with_link():
# Starting a new 'parent_span' which may later link to other spans
with tracer.start_as_current_span("parent_span") as parent_span:
# A common scenario is to correlate one or more traces with the current span.
# This can help in tracing and debugging complex interactions across different parts of the app.
result = roll_dice(parent_span)
return f"Dice roll result (with link): {result}"
def roll():
# Function to generate a random number between 1 and 6
return randint(1, 6)
if __name__ == "__main__":
# Starting the Flask server on the specified PORT and enabling debug mode
app.run(port=8080, debug=True)
```
## Create an exporter.py file
Create an `exporter.py` file with the following content. This file establishes an OpenTelemetry configuration and sets up an exporter that sends trace data to Axiom.
```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
# Define the service name resource for the tracer.
resource = Resource(attributes={
SERVICE_NAME: "NAME_OF_SERVICE" # Replace `NAME_OF_SERVICE` with the name of the service you want to trace.
})
# Create a TracerProvider with the defined resource for creating tracers.
provider = TracerProvider(resource=resource)
# Configure the OTLP/HTTP Span Exporter with Axiom headers and endpoint. Replace `API_TOKEN` with your Axiom API key, and replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
otlp_exporter = OTLPSpanExporter(
endpoint="https://api.axiom.co/v1/traces",
headers={
"Authorization": "Bearer API_TOKEN",
"X-Axiom-Dataset": "DATASET_NAME"
}
)
# Create a BatchSpanProcessor with the OTLP exporter to batch and send trace spans.
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
# Set the TracerProvider as the global tracer provider.
trace.set_tracer_provider(provider)
# Define a tracer for external use in different parts of the app.
service1_tracer = trace.get_tracer("service1")
```
In the `exporter.py` file, make the following changes:
* Replace `NAME_OF_SERVICE` with the name of the service you want to trace. This is important for identifying and categorizing trace data, particularly in systems with multiple services.
* Replace `API_TOKEN` with your Axiom API key.
* Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
For more information on the libraries imported by the `exporter.py` file, see the [Reference](#reference) below.
## Run the app
Run the following code in your terminal to run the Python project:
macOS/Linux
```bash
python3 app.py
```
Windows
```
py -3 app.py
```
In your browser, go to `http://127.0.0.1:8080/rolldice` to interact with your Python app. Each time you load the page, the app displays a random number and sends the collected traces to Axiom.
## Observe the telemetry data in Axiom
In Axiom, go the **Stream** tab and click your dataset. This page displays the traces sent to Axiom and enables you to monitor and analyze your app’s performance and behavior.
## Dynamic OpenTelemetry traces dashboard
In Axiom, go the **Dashboards** tab and click **OpenTelemetry Traces (python)**. This pre-built traces dashboard provides further insights into the performance and behavior of your app.
## Send data from an existing Python project
### Manual instrumentation
Manual instrumentation in Python with OpenTelemetry involves adding code to create and manage spans around the blocks of code you want to trace. This approach allows for precise control over the trace data.
1. Import and configure a tracer at the start of your main Python file. For example, use the tracer from the `exporter.py` configuration.
```python
import exporter
tracer = exporter.service1_tracer
```
2. Enclose the code blocks in your app that you want to trace within spans. Start and end these spans in your code.
```python
with tracer.start_as_current_span("operation_name"):
```
3. Add relevant metadata and logs to your spans to enrich the trace data, providing more context for your data.
```python
with tracer.start_as_current_span("operation_name") as span:
span.set_attribute("key", "value")
```
### Automatic instrumentation
Automatic instrumentation in Python with OpenTelemetry simplifies the process of adding telemetry data to your app. It uses pre-built libraries that automatically instrument the frameworks and libraries.
1. Install the OpenTelemetry packages designed for specific frameworks like Flask or Django.
```bash
pip install opentelemetry-instrumentation-flask
```
2. Configure your app to use these libraries that automatically generate spans for standard operations.
```python
from opentelemetry.instrumentation.flask import FlaskInstrumentor
# This assumes `app` is your Flask app.
FlaskInstrumentor().instrument_app(app)
```
After you set them up, these libraries automatically trace relevant operations without additional code changes in your app.
## Reference
### List of OpenTelemetry trace fields
| Field Category | Field Name | Description |
| ------------------- | --------------------------------------- | ------------------------------------------------------ |
| Unique Identifiers | | |
| | \_rowid | Unique identifier for each row in the trace data. |
| | span\_id | Unique identifier for the span within the trace. |
| | trace\_id | Unique identifier for the entire trace. |
| Timestamps | | |
| | \_systime | System timestamp when the trace data was recorded. |
| | \_time | Timestamp when the actual event being traced occurred. |
| HTTP Attributes | | |
| | attributes.custom\["http.host"] | Host information where the HTTP request was sent. |
| | attributes.custom\["http.server\_name"] | Server name for the HTTP request. |
| | attributes.http.flavor | HTTP protocol version used. |
| | attributes.http.method | HTTP method used for the request. |
| | attributes.http.route | Route accessed during the HTTP request. |
| | attributes.http.scheme | Protocol scheme (HTTP/HTTPS). |
| | attributes.http.status\_code | HTTP response status code. |
| | attributes.http.target | Specific target of the HTTP request. |
| | attributes.http.user\_agent | User agent string of the client. |
| Network Attributes | | |
| | attributes.net.host.port | Port number on the host receiving the request. |
| | attributes.net.peer.port | Port number on the peer (client) side. |
| | attributes.custom\["net.peer.ip"] | IP address of the peer in the network interaction. |
| Operational Details | | |
| | duration | Time taken for the operation. |
| | kind | Type of span (for example,, server, client). |
| | name | Name of the span. |
| | scope | Instrumentation scope. |
| | service.name | Name of the service generating the trace. |
### List of imported libraries
The `exporter.py` file imports the following libraries:
from opentelemetry import trace
This module creates and manages trace data in your app. It creates spans and tracers which track the execution flow and performance of your app.
from opentelemetry.sdk.trace import TracerProvider
`TracerProvider` acts as a container for the configuration of your app’s tracing behavior. It allows you to define how spans are generated and processed, essentially serving as the central point for managing trace creation and propagation in your app.
from opentelemetry.sdk.trace.export import BatchSpanProcessor
`BatchSpanProcessor` is responsible for batching spans before they are exported. This is an important aspect of efficient trace data management as it aggregates multiple spans into fewer network requests, reducing the overhead on your app’s performance and the tracing backend.
from opentelemetry.sdk.resources import Resource, SERVICE\_NAME
The `Resource` class is used to describe your app’s service attributes, such as its name, version, and environment. This contextual information is attached to the traces and helps in identifying and categorizing trace data, making it easier to filter and analyze in your monitoring setup.
from opentelemetry.exporter.otlp.proto.http.trace\_exporter import OTLPSpanExporter
The `OTLPSpanExporter` is responsible for sending your app’s trace data to a backend that supports the OTLP such as Axiom. It formats the trace data according to the OTLP standards and transmits it over HTTP, ensuring compatibility and standardization in how telemetry data is sent across different systems and services.
# Send OpenTelemetry data from a Ruby on Rails app to Axiom
This guide explains how to send OpenTelemetry data from a Ruby on Rails App to Axiom using the Ruby OpenTelemetry SDK.
This guide provides detailed steps on how to configure OpenTelemetry in a Ruby application to send telemetry data to Axiom using the [OpenTelemetry Ruby SDK](https://opentelemetry.io/docs/languages/ruby/).
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/).
* [Create a dataset](/reference/settings#data) where you want to send data.
* [Create an API token in Axiom with permissions to ingest and query data](/reference/tokens).
* Install a [Ruby version manager](https://www.ruby-lang.org/en/documentation/installation/) like `rbenv` and use it to install the latest Ruby version.
* Install [Rails](https://guides.rubyonrails.org/v5.0/getting_started.html) using the `gem install rails` command.
## Set up the Ruby on Rails application
1. Create a new Rails app using the `rails new myapp` command.
2. Go to the app directory with the `cd myapp` command.
3. Open the `Gemfile` and add the following OpenTelemetry packages:
```ruby
gem 'opentelemetry-api'
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-rails'
gem 'opentelemetry-instrumentation-http'
gem 'opentelemetry-instrumentation-active_record', require: false
gem 'opentelemetry-instrumentation-all'
```
Install the dependencies by running `bundle install`.
## Configure the OpenTelemetry exporter
In the `initializers` folder of your Rails app, create a new file called `opentelemetry.rb`, and then add the following OpenTelemetry exporter configuration:
```ruby
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
c.service_name = 'ruby-traces' # Set your service name
c.use_all # Or specify individual instrumentation you need
c.add_span_processor(
OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
OpenTelemetry::Exporter::OTLP::Exporter.new(
endpoint: 'https://api.axiom.co/v1/traces',
headers: {
'Authorization' => 'Bearer API_TOKEN',
'X-AXIOM-DATASET' => 'DATASET_NAME'
}
)
)
)
end
```
In the code above, make the following changes:
* Replace `API_TOKEN` with your Axiom API key.
* Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
## Run the instrumented application
Run your Ruby on Rails application with OpenTelemetry instrumentation.
### In development mode
Start the Rails server using the `rails server` command. The server will start on the default port (usually 3000), and you can access your application by visiting `http://localhost:3000` in your web browser.
As you interact with your application, OpenTelemetry automatically collects telemetry data and sends it to Axiom using the configured OTLP exporter.
### In production mode
For production, ensure to precompile assets and run migrations if necessary. Start the server with `RAILS_ENV=production bin/rails server`. This setup ensures your Ruby application is instrumented to send traces to Axiom, using OpenTelemetry for observability.
## Observe the telemetry data in Axiom
As you interact with your application, traces are collected and exported to Axiom, allowing you to monitor, analyze, and gain insights into your application’s performance and behavior.
1. In your Axiom account and click on the **Datasets** or **Stream** tab.
2. Select your dataset from the list.
3. From the list of fields, click on the **trace\_id** to view your spans.
## Dynamic OpenTelemetry Traces dashboard
This data can then be further viewed and analyzed in Axiom’s dashboard, offering a deeper understanding of your application’s performance and behavior.
1. In your Axiom account, select **Dashboards**, and click on the traces dashboard named after your dataset.
2. View the dashboard which displays your total traces, incoming spans, average span duration, errors, slowest operations, and top 10 span errors across services.
## Send data from an existing Ruby app
### Manual instrumentation
Manual instrumentation allows users to define and manage telemetry data collection points within their Ruby applications, providing granular control over what is traced.
1. Initialize Tracer. Use the OpenTelemetry API to obtain a tracer from the global tracer provider. This tracer will be used to start and manage spans.
```ruby
tracer = OpenTelemetry.tracer_provider.tracer('my-tracer')
```
2. Manually start a span at the beginning of the block of code you want to trace and ensure to end it when your operations complete. This is useful for gathering detailed data about specific operations.
```ruby
span = tracer.start_span('operation_name')
begin
# Perform operation
rescue => e
span.record_exception(e)
span.status = OpenTelemetry::Trace::Status.error("Operation failed")
ensure
span.finish
end
```
3. Enhance spans with custom attributes to provide additional context about the traced operations, helping in debugging and monitoring performance.
```ruby
span.set_attribute("user_id", user.id)
span.add_event("query_executed", attributes: { "query" => sql_query })
```
### Automatic instrumentation
Automatic instrumentation in Ruby uses OpenTelemetry’s libraries to automatically generate telemetry data for common operations, such as HTTP requests and database queries.
1. Set up the OpenTelemetry SDK with the necessary instrumentation libraries in your Ruby application. This typically involves modifying the Gemfile and an initializer to set up the SDK and auto-instrumentation.
```ruby
# In config/initializers/opentelemetry.rb
OpenTelemetry::SDK.configure do |c|
c.service_name = 'ruby-traces'
c.use_all # Automatically use all available instrumentation
end
```
2. Ensure your Gemfile includes gems for the automatic instrumentation of the frameworks and libraries your application uses.
```ruby
gem 'opentelemetry-instrumentation-rails'
gem 'opentelemetry-instrumentation-http'
gem 'opentelemetry-instrumentation-active_record'
```
After setting up, no additional manual changes are required for basic telemetry data collection. The instrumentation libraries handle the creation and management of telemetry data automatically.
## Reference
### List of OpenTelemetry trace fields
| Field Category | Field Name | Description |
| ------------------------------- | ------------------------------------ | ------------------------------------------------------------- |
| **General Trace Information** | | |
| | \_rowId | Unique identifier for each row in the trace data. |
| | \_sysTime | System timestamp when the trace data was recorded. |
| | \_time | Timestamp when the actual event being traced occurred. |
| | trace\_id | Unique identifier for the entire trace. |
| | span\_id | Unique identifier for the span within the trace. |
| | parent\_span\_id | Unique identifier for the parent span within the trace. |
| **HTTP Attributes** | | |
| | attributes.http.method | HTTP method used for the request. |
| | attributes.http.status\_code | HTTP status code returned in response. |
| | attributes.http.target | Specific target of the HTTP request. |
| | attributes.http.scheme | Protocol scheme (HTTP/HTTPS). |
| **User Agent** | | |
| | attributes.http.user\_agent | User agent string, providing client software and OS. |
| **Custom Attributes** | | |
| | attributes.custom\["http.host"] | Host information where the HTTP request was sent. |
| | attributes.custom.identifier | Path to a file or identifier in the trace context. |
| | attributes.custom.layout | Layout used in the rendering process of a view or template. |
| **Resource Process Attributes** | | |
| | resource.process.command | Command line string used to start the process. |
| | resource.process.pid | Process ID. |
| | resource.process.runtime.description | Description of the runtime environment. |
| | resource.process.runtime.name | Name of the runtime environment. |
| | resource.process.runtime.version | Version of the runtime environment. |
| **Operational Details** | | |
| | duration | Time taken for the operation. |
| | kind | Type of span (e.g., server, client, internal). |
| | name | Name of the span, often a high-level title for the operation. |
| **Code Attributes** | | |
| | attributes.code.function | Function or method being executed. |
| | attributes.code.namespace | Namespace or module that includes the function. |
| **Scope Attributes** | | |
| | scope.name | Name of the scope for the operation. |
| | scope.version | Version of the scope. |
| **Service Attributes** | | |
| | service.name | Name of the service generating the trace. |
| | service.version | Version of the service generating the trace. |
| | service.instance.id | Unique identifier for the instance of the service. |
| **Telemetry SDK Attributes** | | |
| | telemetry.sdk.language | Language of the telemetry SDK, e.g., ruby. |
| | telemetry.sdk.name | Name of the telemetry SDK, e.g., opentelemetry. |
| | telemetry.sdk.version | Version of the telemetry SDK, e.g., 1.4.1. |
### List of imported libraries
`gem 'opentelemetry-api'`
The `opentelemetry-api` gem provides the core OpenTelemetry API for Ruby. It defines the basic concepts and interfaces for distributed tracing, such as spans, tracers, and context propagation. This gem is essential for instrumenting your Ruby application with OpenTelemetry.
`gem 'opentelemetry-sdk'`
The `opentelemetry-sdk` gem is the OpenTelemetry SDK for Ruby. It provides the implementation of the OpenTelemetry API, including the tracer provider, span processors, and exporters. This gem is responsible for managing the lifecycle of spans and sending them to the specified backend.
`gem 'opentelemetry-exporter-otlp'`
The `opentelemetry-exporter-otlp` gem is an exporter that sends trace data to a backend that supports the OpenTelemetry Protocol (OTLP), such as Axiom. It formats the trace data according to the OTLP standards and transmits it over HTTP or gRPC, ensuring compatibility and standardization in how telemetry data is sent across different systems and services.
`gem 'opentelemetry-instrumentation-rails'`
The `opentelemetry-instrumentation-rails` gem provides automatic instrumentation for Ruby on Rails applications. It integrates with various aspects of a Rails application, such as controllers, views, and database queries, to capture relevant trace data without requiring manual instrumentation. This gem simplifies the process of adding tracing to your Rails application.
`gem 'opentelemetry-instrumentation-http'`
The `opentelemetry-instrumentation-http` gem provides automatic instrumentation for HTTP requests made using the `Net::HTTP` library. It captures trace data for outgoing HTTP requests, including request headers, response status, and timing information. This gem helps in tracing the external dependencies of your application.
`gem 'opentelemetry-instrumentation-active_record', require: false`
The `opentelemetry-instrumentation-active_record` gem provides automatic instrumentation for ActiveRecord, the Object-Relational Mapping (ORM) library used in Ruby on Rails. It captures trace data for database queries, including the SQL statements executed and their duration. This gem helps in identifying performance bottlenecks related to database interactions.
`gem 'opentelemetry-instrumentation-all'`
The `opentelemetry-instrumentation-all` gem is a meta-gem that includes all the available instrumentation libraries for OpenTelemetry in Ruby. It provides a convenient way to install and configure multiple instrumentation libraries at once, covering various aspects of your application, such as HTTP requests, database queries, and external libraries. This gem simplifies the setup process and ensures comprehensive tracing coverage for your Ruby application.
# Axiom transport for Pino logger
This page explains how to send data from a Node.js app to Axiom through Pino.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
## Install SDK
To install the SDK, run the following:
```shell
npm install @axiomhq/pino
```
## Create Pino logger
The example below creates a Pino logger with Axiom configured:
```ts
import pino from 'pino';
const logger = pino(
{ level: 'info' },
pino.transport({
target: '@axiomhq/pino',
options: {
dataset: process.env.AXIOM_DATASET,
token: process.env.AXIOM_TOKEN,
},
}),
);
```
After setting up the Axiom transport for Pino, use the logger as usual:
```js
logger.info('Hello from Pino!');
```
## Examples
For more examples, see the [examples in GitHub](https://github.com/axiomhq/axiom-js/tree/main/examples/pino).
# Send data from Python app to Axiom
This page explains how to send data from a Python app to Axiom.
To send data from a Python app to Axiom, use the Axiom Python SDK.
## Conclusion
This guide has introduced you to integrating Axiom for logging in Laravel apps. You've learned how to create a custom logger, configure log channels, and understand the significance of log levels. With this knowledge, you’re set to track errors and analyze log data effectively using Axiom.
# Send logs from a Ruby on Rails application using Faraday
This guide provides step-by-step instructions on how to send logs from a Ruby on Rails application to Axiom using the Faraday library.
This guide provides step-by-step instructions on how to send logs from a Ruby on Rails application to Axiom using the Faraday library. By following this guide, you configure your Rails app to send logs to Axiom, allowing you to monitor and analyze your application logs effectively.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/).
* [Create a dataset](/reference/settings#data) where you want to send data.
* [Create an API token in Axiom with permissions to ingest and query data](/reference/tokens).
* Install a [Ruby version manager](https://www.ruby-lang.org/en/documentation/installation/) like `rbenv` and use it to install the latest Ruby version.
* Install [Ruby on Rails](https://guides.rubyonrails.org/v5.0/getting_started.html) using the `gem install rails` command.
## Set up the Ruby on Rails application
1. Create a new Rails app using the `rails new myapp` command.
2. Navigate to the app directory: `cd myapp`
## Setting up the Gemfile
Open the `Gemfile` in your Rails app, and then add the following gems:
```ruby
gem 'faraday'
gem 'dotenv-rails', groups: [:development, :test]
```
Install the dependencies by running `bundle install`.
## Create and configure the Axiom logger
1. Create a new file named `axiom_logger.rb` in the `app/services` directory of your Rails app.
2. Add the following code to `axiom_logger.rb`:
```ruby
# app/services/axiom_logger.rb
require 'faraday'
require 'json'
class AxiomLogger
def self.send_log(log_data)
dataset_name = "DATASET_NAME"
axiom_ingest_api_url = "https://api.axiom.co/v1/datasets/#{dataset_name}/ingest"
ingest_token = "API_TOKEN"
conn = Faraday.new(url: axiom_ingest_api_url) do |faraday|
faraday.request :url_encoded
faraday.adapter Faraday.default_adapter
end
wrapped_log_data = [log_data]
response = conn.post do |req|
req.headers['Content-Type'] = 'application/json'
req.headers['Authorization'] = "Bearer #{ingest_token}"
req.body = wrapped_log_data.to_json
end
puts "AxiomLogger Response status: #{response.status}, body: #{response.body}"
if response.status != 200
Rails.logger.error "Failed to send log to Axiom: #{response.body}"
end
end
end
```
In the code above, make the following changes:
* Replace `API_TOKEN` with your Axiom API key.
* Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
## Test with the Axiom logger
1. Create a new file named `axiom_logger_test.rb` in the `config/initializers` directory.
2. Add the following code to `axiom_logger_test.rb`:
```ruby
# config/initializers/axiom_logger_test.rb
Rails.application.config.after_initialize do
puts "Sending test logs to Axiom using Ruby on Rails Faraday..."
# Info logs
AxiomLogger.send_log({ message: "Application started successfully", level: "info", service: "initializer" })
AxiomLogger.send_log({ message: "User authentication successful", level: "info", service: "auth" })
AxiomLogger.send_log({ message: "Data fetched from external API", level: "info", service: "external_api" })
AxiomLogger.send_log({ message: "Email notification sent", level: "info", service: "email" })
# Warn logs
AxiomLogger.send_log({ message: "API request took longer than expected", level: "warn", service: "external_api", duration: 1500 })
AxiomLogger.send_log({ message: "User authentication token expiring soon", level: "warn", service: "auth", user_id: 123 })
AxiomLogger.send_log({ message: "Low disk space warning", level: "warn", service: "system", disk_usage: "85%" })
AxiomLogger.send_log({ message: "Non-critical configuration issue detected", level: "warn", service: "config" })
# Error logs
AxiomLogger.send_log({ message: "Database connection error", level: "error", service: "database", error: "Timeout" })
AxiomLogger.send_log({ message: "Failed to process payment", level: "error", service: "payment", user_id: 456, error: "Invalid card" })
AxiomLogger.send_log({ message: "Unhandled exception occurred", level: "error", service: "application", exception: "NoMethodError" })
AxiomLogger.send_log({ message: "Third-party API returned an error", level: "error", service: "integration", status_code: 500 })
# Debug logs
AxiomLogger.send_log({ message: "Request parameters", level: "debug", service: "api", params: { page: 1, limit: 20 } })
AxiomLogger.send_log({ message: "Response headers", level: "debug", service: "api", headers: { "Content-Type" => "application/json" } })
AxiomLogger.send_log({ message: "User object details", level: "debug", service: "user", user: { id: 789, name: "Axiom Observability", email: "support@axiom.co" } })
AxiomLogger.send_log({ message: "Cache hit for key", level: "debug", service: "cache", key: "popular_products" })
end
```
Each log entry includes a message, level, service, and additional relevant data.
* Info logs:
* Application started successfully
* User authentication successful
* Data fetched from external API
* Email notification sent
* Warn logs:
* API request took longer than expected (including duration)
* User authentication token expiring soon (including user ID)
* Low disk space warning (including disk usage percentage)
* Non-critical configuration issue detected
* Error logs:
* Database connection error (including error message)
* Failed to process payment (including user ID and error message)
* Unhandled exception occurred (including exception type)
* Third-party API returned an error (including status code)
* Debug logs:
* Request parameters (including parameter values)
* Response headers (including header key-value pairs)
* User object details (including user attributes)
* Cache hit for key (including cache key)
Adjust the log messages, services, and additional data according to your application’s specific requirements and context.
## Create the `log.rake` tasks
1. Create a new directory named `tasks` in the `lib` directory of your Rails app.
2. Create a new file named `log.rake` in the `lib/tasks` directory.
3. Add the following code to `log.rake`:
```ruby
# lib/tasks/log.rake
namespace :log do
desc "Send a test log to Axiom"
task send_test_log: :environment do
log_data = { message: "Hello, Axiom from Rake!", level: "info", service: "rake_task" }
AxiomLogger.send_log(log_data)
puts "Test log sent to Axiom."
end
end
```
This code defines a Rake task that sends a test log to Axiom when invoked.
## View logs in Axiom
1. Start your Rails server by running `rails server`.
2. Go to `http://localhost:3000` to trigger the test log from the initializer.
3. Run the Rake task to send another test log by executing `rails log:send_test_log` in your terminal.
4. In Axiom, go to the Stream tab, and then select the dataset where you send the logs.
5. You see the test logs appear allowing you to view and analyze your event data coming from your Ruby on Rails application.
## Conclusion
You have successfully set up your Ruby on Rails application to send logs to Axiom using the Faraday library. With this configuration, you can centralize your application logs and use Axiom’s powerful features like [APL](/apl/introduction) for log querying, monitoring, and observing various log levels and types effectively.
# Axiom transport for Winston logger
This page explains how to send data from a Node.js app to Axiom through Winston.
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
## Install SDK
To install the SDK, run the following:
```shell
npm install @axiomhq/winston
```
## Import the Axiom transport for Winston
```js
import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';
```
## Create a Winston logger instance
```js
const logger = winston.createLogger({
level: 'info',
format: winston.format.json(),
defaultMeta: { service: 'user-service' },
transports: [
// You can pass an option here. If you don’t, the transport is configured automatically
// using environment variables like `AXIOM_DATASET` and `AXIOM_TOKEN`
new AxiomTransport({
dataset: 'my-dataset',
token: 'my-token',
}),
],
});
```
After setting up the Axiom transport for Winston, use the logger as usual:
```js
logger.log({
level: 'info',
message: 'Logger successfully setup',
});
```
### Error, exception, and rejection handling
To log errors, use the [`winston.format.errors`](https://github.com/winstonjs/logform#errors) formatter. For example:
```ts
import winston from 'winston';
import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';
const { combine, errors, stack } = winston.format;
const axiomTransport = new AxiomTransport({ ... });
const logger = winston.createLogger({
// 8<----snip----
format: combine(errors({ stack: true }), json()),
// 8<----snip----
});
```
To automatically log exceptions and rejections, add the Axiom transport to the [`exceptionHandlers`](https://github.com/winstonjs/winston#exceptions) and [`rejectionHandlers`](https://github.com/winstonjs/winston#rejections). For example:
```ts
import winston from 'winston';
import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';
const axiomTransport = new AxiomTransport({ ... });
const logger = winston.createLogger({
// 8<----snip----
transports: [axiomTransport],
exceptionHandlers: [axiomTransport],
rejectionHandlers: [axiomTransport],
// 8<----snip----
});
```
To dive right in, read the [Get started guide](/getting-started-guide/getting-started).
The Axiom documentation enables you to gain a deeper understanding of what Axiom is, how to get it installed, and how best to use it for your organization’s use case. See below for a list of the most common use cases.
.
4. Click **Delete**.
# Configure notifiers
This page explains how to configure notifiers.
## Disable notifiers
Disable a monitor to prevent it from running for a specific amount of time.
To disable a notifier:
1. Click the Monitors tab.
2. In the left, click **Notifiers**.
3. Click the notifier in the list that you want to disable.
4. In the top right, click **Disable notifier**.
5. Select the time period for which you want to disable the notifier.
6. Click **Disable**.
Axiom automatically enables the notifier after the time period you specified.
## Enable notifiers
To enable a notifier:
1. Click the Monitors tab.
2. In the left, click **Notifiers**.
3. Click the notifier in the list that you want to enable.
4. In the top right, click **Enable notifier**.
5. Click **Enable**.
## Delete notifiers
To delete a notifier:
1. Click the Monitors tab.
2. In the left, click **Notifiers**.
3. Click the notifier in the list that you want to delete.
4. In the top right, click .
5. Click **Delete**.
# Custom webhook notifier
This page explains how to create and configure a custom webhook notifier.
Use a custom webhook notifier to connect your monitors to internal or external services. The webhook URL receives a POST request with a content type of `application/json` together with any other headers you specify.
To create a custom webhook notifier, follow these steps:
1. Click the **Monitors** tab, and then click **Manage notifiers** on the right.
2. Click **New notifier** on the top right.
3. Name your notifier.
4. Click **Custom webhook**.
5. In **Webhook URL**, enter the URL where you want to send the POST request.
6. Optional: To customize the content of your webhook, use the Go template syntax to interact with these variables:
* `.Action` has value `Open` when the notification corresponds to a match monitor matching or a threshold monitor triggering, and has value `Closed` when the notification corresponds to a threshold monitor resolving.
* `.MonitorID` is the unique identifier for the monitor associated with the notification.
* `.Body` is the message body associated with the notification. When the notification corresponds to a match monitor, this is the matching event data. When the notification corresponds to a threshold monitor, this provides information about the value that gave rise to the monitor triggering or resolving.
* `.Description` is the description of the monitor associated with the notification.
* `.QueryEndTime` is the end time applied in the monitor query that gave rise to the notification.
* `.QueryStartTime` is the start time applied in the monitor query that gave rise to the notification.
* `.Timestamp` is the time the notification was generated.
* `.Title` is the name of the monitor associated with the notification.
* `.Value` is the value that gave rise to the monitor triggering or resolving when the notification corresponds to a threshold monitor.
* `.MatchedEvent` is the event that matched the criteria of a match monitor.
7. Optional: Add headers to the POST request sent to the webhook URL.
8. Click **Create**.
## Example
The example below is a custom webhook notification generated from a threshold monitor triggering. The body of a POST request sent to the webhook URL using the default template is the following:
```json
{
"action": "Open",
"event": {
"monitorID": "CabI3w142069etTgd0",
"body": "Current value of 57347 is above or equal to the threshold value of 0",
"description": "",
"queryEndTime": "2024-06-28 14:55:57.631364493 +0000 UTC",
"queryStartTime": "2024-06-28 14:45:57.631364493 +0000 UTC",
"timestamp": "2024-06-28 14:55:57 +0000 UTC",
"title": "Axiom Monitor Test Triggered",
"value": 57347,
"matchedEvent": null
}
}
```
# Discord notifier
This page explains how to create and configure a Discord notifier.
Use a Discord notifier to notify specific channels in your Discord server.
To create a Discord notifier, choose one of the following methods:
* [Create Discord notifier with a token](#create-discord-notifier-with-token)
* [Create Discord notifier with a webhook URL](#create-discord-notifier-with-webhook)
## Create Discord notifier with token
In Discord, create a token and get the channel ID:
1. Go to [Discord .dev](https://discord.com/developers/applications) and create a new application.
2. Click **Bot > Add Bot > Reset Token** to get your Discord token.
3. Click **OAuth2 > URL Generator**, check the Bot scope and the Send Messages permission.
4. Open the generated URL to add the bot to your server.
5. Click **User Settings > Advanced**, and then enable developer mode.
6. Right-click a channel, and then click **Copy ID**.
7. Ensure the **Discord Bot** has the proper allow channel access permissions.
In Axiom:
1. Click the **Monitors** tab, and then click **Manage notifiers** on the right.
2. Click **New notifier** on the top right.
3. Name your notifier.
4. Click **Discord**.
5. Enter the token you have previously generated and the channel ID.
6. Click **Create**.
### Create Discord notifier with webhook
1. In Discord, generate a webhook. For more information, see the [Discord documentation](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).
2. In Axiom, click the **Monitors** tab, and then click **Manage notifiers** on the right.
3. Click **New notifier** on the top right.
4. Name your notifier.
5. Click **Discord Webhook**.
6. Enter the webhook URL you have previously generated.
7. Click **Create**.
# Email notifier
This page explains how to create and configure an email notifier.
To create an email notifier, follow these steps:
1. Click the **Monitors** tab, and then click **Manage notifiers** on the right.
2. Click **New notifier** on the top right.
3. Name your notifier.
4. Click **Email**.
5. In the **Users** section, add the email addresses where you want to send notifications, and then click **+** on the right.
6. Click **Create**.
# Match monitors
This section introduces the Monitors tab and explains how to create monitors.
Match monitors allow you to continuously filter your log data and send you matching events. Axiom sends a notification for each matching event. By default, the notification message contains the entire matching event in JSON format. When you define your match monitor using APL, you can control which event attributes to include in the notification message.
Axiom recommends using match monitors for alerting purposes only. A match monitor can send 10 notifications per minute and 500 notifications per day.
## Create match monitor
To create a match monitor, follow these steps:
1. Click the **Monitors** tab, and then click **New monitor**.
2. Click **Match monitor**.
3. Name your monitor and add a description.
4. Click **Add notifier**, and then select the notifiers that define how you want to receive notifications for this monitor. For more information, see [Notifiers](#notifiers).
5. To define your query, use one of the following options:
* To use the visual query builder, click **Simple query builder**. Select the filters, and then click **Run query** to preview the recent events that match your filters. To preview matching events over a specific period, select the time range.
* To use Axiom Processing Language (APL), click **Advanced query language**. Write a query using the `where` operator to filter for events, and then click **Run query** to preview the results. To transform matching events before sending them to you, use the `extend` and the `project` operators. Don’t use aggregations in your query. For more information, see [Introduction to APL](/apl/introduction).
6. When the preview displays the events that you want to match, click **Create**. You cannot create a match monitor if more than 500 events match your query within the past 24 hours.
You have created a match monitor, and Axiom alerts you about every event that matches the filters you set. Each notification contains the event details as shown in the preview.
## Examples
For real-world use cases, see [Monitor examples](/monitor-data/monitor-examples).
# Microsoft Teams notifier
This page explains how to create and configure a Microsoft Teams notifier.
Use a Microsoft Teams notifier to send a notification to a specific channel in your Microsoft Teams instance.
To create a Microsoft Teams notifier, follow these steps:
1. In Microsoft Teams, generate an incoming webhook. For more information, see the [Microsoft documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook).
2. In Axiom, click the **Monitors** tab, and then click **Manage notifiers** on the right.
3. Click **New notifier** on the top right.
4. Name your notifier.
5. Click **Microsoft Teams**.
6. Enter the webhook URL you have previously generated.
7. Click **Create**.
# Monitor examples
This page presents example monitor configurations for some common alerting use cases.
## Notify on all occurrences of error
To receive a notification on all occurrences of an error, create a match monitor where the filter conditions match the events reporting the error.
To receive only certain attributes in the notification message, use the `project` operator.
## Notify when error rate above threshold
To receive a notification when the error rate exceeds a threshold, [create a threshold monitor](/monitor-data/threshold-monitors) with an APL query that identifies the rate of error messages.
For example, logs in your dataset `['sample_dataset']` have a `status.code` attribute that takes the value `ERROR` when a log is about an error. In this case, the following example query tracks the error rate every minute:
```apl
['sample_dataset']
| extend is_error = case(['status.code'] == 'ERROR', 1, 0)
| summarize avg(error) by bin(_time, 1m)
```
Other options:
* To trigger the monitor when the error rate is above or equal to 0.01, set the threshold value to 0.01 and the comparison operator to `above or equal`.
* To run the monitor every 5 minutes, set the frequency to 5.
* To keep the monitor in the alert state until 10 minutes have passed with the per-minute error rate remaining below your threshold value, set the range to 10.
## Notify when number of error messages above threshold
To receive a notification when the number of error message of a given type exceeds a threshold, create a threshold monitor with an APL query that counts the different error messages.
For example, logs in your dataset `['sample_dataset']` have a `error.message` attribute. In this case, the following example query counts errors by type every 5 minutes:
```apl
['sample_dataset']
| summarize count() by ['error.message'], bin(_time, 5m)
```
Other options:
* To trigger the monitor when the count is above or equal to 10 for any individual message type, set the threshold to 10 and the comparison operator to **above or equal**.
* To run the monitor every 5 minutes, set the frequency to 5.
* To run the monitor the query with a range of 10 minutes, set the range to 10.
By default, the monitor enters the alert state when any of the counts returned by the query cross the threshold, and remains in the alert state until no counts cross the threshold. To alert separately for each message value instead, enable **Notify by group**.
## Notify when response times spike
To receive a notification whenever your response times spike without having to rely on a single threshold, [create an anomaly monitor](/monitor-data/anomaly-monitors) with an APL query that tracks your median response time.
For example, you have a dataset `['my_traces']` of trace data with the following:
* Route information is in the `route` field.
* Duration information is in the `duration` field.
* For top-level spans, the `parent_span_id` field is empty.
The following query gives median response times by route in one-minute intervals:
```apl
['my_traces']
| where isempty(parent_span_id)
| summarize percentile(duration, 50) by ['route'], bin(_time, 1m)
```
Other options:
* To only trigger the monitor when response times are unusually high for a route, set the comparison operator to **above**.
* To run the monitor every 5 minutes, set the frequency to 5.
* To consider the previous 30 minutes of data when determining what sort of variation is expected for median response times for a route, set the range to 30.
* To notify separately for each route, enable **Notify by group**.
# Monitors
This section introduces monitors and explains how you can use them to generate automated alerts from your event data.
A monitor is a background task that periodically runs a query that you define. For example, it counts the number of error messages in your logs over the previous 5 minutes. A notifier defines how Axiom notifies you about the monitor output. For example, Axiom can send you an email.
You can use the following types of monitor:
* [Anomaly monitors](/monitor-data/anomaly-monitors) aggregate event data over time and look for values that are unexpected based the event history. When the results of the aggregation are too high or low compared to the expected value, Axiom sends you an alert.
* [Match monitors](/monitor-data/match-monitors) filter for key events and send them to you.
* [Threshold monitors](/monitor-data/threshold-monitors) aggregate event data over time. When the results of the aggregation cross a threshold, Axiom sends you an alert.
# Notifiers
This section introduces notifiers and explains how you can use them to generate automated alerts from your event data.
This section introduces notifiers and explains how you can use them to generate automated alerts from your event data.
A monitor is a background task that periodically runs a query that you define. For example, it counts the number of error messages in your logs over the previous 5 minutes. A notifier defines how Axiom notifies you about the monitor output. For example, Axiom can send you an email.
By adding a notifier to a monitor, you receive a notification with the following message:
* When a match monitor matches an event, the message contains the full event if you created the monitor using the simple query builder, or the output of the APL query if you created the monitor using APL.
* When a threshold monitor changes state, the message includes a relevant value from the query results. If you enable **Notify by group**, the notification message also contains the relevant group value.
Choose one of the following to learn more about a type of notifier:
**Toggle annotations**.
3. Select the datasets whose annotations you want to display on the charts.
## Example use case
The example below demonstrates how annotations help you troubleshoot issues in your app or system. Your monitor alerts you about rising form submission errors. You explore this trend and when it started. Right before form submission errors started rising, you see an annotation about a deployment of a new feature to the form. You make the hypothesis that the deployment is the reason for the error and decide to investigate the code changes it introduced.
### Create annotation
Use the following API request to create an annotation:
```bash
curl -X 'POST' 'https://api.axiom.co/v2/annotations' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"time": "2024-03-18T08:39:28.382Z",
"type": "deploy",
"datasets": ["my-dataset"],
"title": "Production deployment",
"description": "Deploy new feature to the sales form",
"url": "https://example.com"
}'
```
In the code above, replace `API_TOKEN` with your Axiom API token.
### Create a monitor
In this example, you set up a monitor that alerts you when the number of form submission errors rises. For more information on creating a monitor, see [Monitoring and Notifiers](/monitor-data/monitors).
### Explore trends
Suppose your monitor sends you a notification about rising form submission errors.
You decide to investigate and run a query to display the number of form submission errors over time. Ensure you select a time range that includes the annotation.
You get a chart similar to the example below displaying form submission errors and annotations about the time of important events such as deployments.
### Inspect issue
1. From the chart, you see that the number of errors started to rise after the deployment of a new feature to the sales form. This correlation allows you to form the hypothesis that the errors might be caused by the deployment.
2. You decide to investigate the deployment by clicking on the link associated with the annotation. The link takes you to the GitHub pull request.
3. You inspect the code changes in depth and discover the cause of the errors.
4. You quickly fix the issue in another deployment.
# Analyze data
This page explains how to use the Datasets tab in Axiom.
The Datasets tab allows you to gain a better understanding of the fields you have in your datasets.
In Axiom, an individual piece of data is an event, and a dataset is a collection of related events. Datasets contain incoming event data. The Datasets tab provides you with information about each field within your datasets.
## Datasets overview
When you open the Datasets tab, you see the list of datasets on the left. To explore the fields in a dataset, select the dataset from the list on the left.
On the right, you see the following:
* The list of integration dashboards appears on the Datasets overview page. These are prebuilt dashboards automatically generated by Axiom to enhance your experience. For more information, see [Apps](/apps).
* The list of [starred queries](#starred-queries)
* The [query history](#query-history)
## Fields list
When you select a dataset, Axiom displays the list of fields within the dataset.
The field types are the following:
* String
* Number
* Boolean
* Array
* [Virtual fields](#virtual-fields)
This view flattens field names with dot notation. This means that the event `{"foo": { "bar": "baz" }}` appears as `foo.bar`. Field names containing periods (`.`) are folded.
### Edit field
Click the field name to change the following:
* Change the field description.
* Change the field unit. This is only available for number field types.
* Hide the field. This means that the field is still present in the underlying Axiom database, but it doesn’t appear in the Axiom UI. Use this option if you sent the field to Axiom by mistake or you don’t want to use it anymore in Axiom.
## Quick charts
Quick charts allow fast charting of fields depending on their field type. For example, for number fields, choose one of the following for easily visualizing
* 
Percentiles
* 
Averages
* 
Histograms
## Virtual fields
Virtual fields are powerful expressions that run on every event during a query to create new fields. The virtual fields are calculated from the events in the query using an APL expression. They’re similar to tools like derived columns in other products but super-charged with an expressive interpreter and with the flexibility to add, edit, or remove them any time.
To manage a dataset’s virtual fields, click 
in the toolbar.
## Queries
Every query has a unique ID that you can save and share with your team members. The Datasets tab allows you to do the following:
* Find a past query.
* Run previously saved queries.
* Star a query so that you and your team members can easily find it in the future.
### Recent queries
To find and run recent queries:
1. Click **Query library** in the toolbar.
2. Click the **Recent** tab.
3. Optional: In the top right, select whether to display 
your queries or 
your team’s queries.
4. Find the query in the list, and then click it to run the query.
### Saved queries
To find and run previously saved queries:
1. Click **Query library** in the toolbar.
2. Click the **Saved** tab.
3. Optional: In the top right, select whether to display your queries or your team’s queries.
4. Find the query in the list, and then click it to run the query.
### Starred queries
In the **Starred queries** section on the right, you see queries saved for future use. They’re great for keeping a list of useful queries for a dataset. All starred queries are shared with your team.
# Explore data with Axiom
Learn how to filter, manipulate, extend, and summarize your data.
The Query tab provides you with robust computation and processing power to get deeper insights into your data. It enables you to filter, manipulate, extend, and summarize your data.
## Use the Query tab
Go to the Query tab and choose one of the following options:
* [Create a query with the visual query builder](#create-a-query-using-the-visual-query-builder).
* [Create a query using Axiom Processing Language (APL)](#create-a-query-using-apl).
You can easily switch between these two methods at any point when creating the query.
## Create a query using the visual query builder
1. In the top left, click **Builder**.
2. From the list, select the dataset that you want to query.
3. Optional: In the **Where** section, create filters to narrow down the query results.
4. Optional: In the **Summarize** section, select a way to visualize the query results.
5. Optional: In the **More** section, specify additional options such as sorting the results or limiting the number of displayed events.
6. Select the time range.
7. Click **Run**.
See below for more information about each of these steps.
### Add filters
Use the **Where** section to filter the results to specific events. For example, to filter for events that originate in a specific geolocation like France.
To add a filter:
1. Click **+** in the **Where** section.
2. Select the field where you want to filter for values. For example, `geo.country`.
3. Select the logical operator of the filter. These are different for each field type. For example, you can use **starts-with** for string fields and **>=** for number fields. In this example, select `==` for an exact match.
4. Specify the value for which you want to filter. In this example, enter `France`.
When you run the query, the results only show events matching the criteria you specified for the filter.
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20where%20%5B'geo.country'%5D%20%3D~%20'France'%22%7D)
### Add multiple filters
You can add multiple filters and combine them with AND/OR operators. For example, to filter for events that originate in France or Germany.
To add and combine multiple filters:
1. Add a filter for France as explained in [Add filters](#add-filters).
2. Add a filter for Germany as explained in [Add filters](#add-filters).
3. Click **and** that appears between the two filters, and then select **or**.
The query results display events that originate in France or Germany.
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20where%20\(%5B'geo.country'%5D%20%3D~%20'France'%20or%20%5B'geo.country'%5D%20%3D~%20'Germany'\)%22%7D)
**Time range**.
2. Choose one of the following options:
* Use the **Quick range** items to quickly select popular time ranges.
* Use the **Custom start/end date** fields to select specific times.
### Special fields
Axiom creates the following two fields automatically for a new dataset:
* `_time` is the timestamp of the event. If the data you ingest doesn’t have a `_time` field, Axiom assigns the time of the data ingest to the events.
* `_sysTime` is the time when you ingested the data.
In most cases, you can use `_time` and `_sysTime` interchangeably. The difference between them can be useful if you experience clock skews on your event-producing systems.
## Create a query using APL
APL is a data processing language that supports filtering, extending, and summarizing data. For more information, see [Introduction to APL](/apl/introduction).
Some APL queries are explained below. The pipe symbol `|` separates the operations as they flow from left to right, and top to bottom.
APL is case-sensitive for everything: dataset names, field names, operators, functions, etc.
Use double forward slashes (`//`) for comments.
### APL count operator
The below query returns the number of events from the `sample-http-logs` dataset.
```kusto
['sample-http-logs']
| summarize count()
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20summarize%20count\(\)%22%7D)
### APL limit operator
The `limit` operator returns a random subset of rows from a dataset up to the specified number of rows. This query returns a thousand rows from `sample-http-logs` randomly chosen by APL.
```kusto
['sample-http-logs']
| limit 1000
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20limit%201000%22%7D)
### APL summarize operator
The `summarize` operator produces a table that aggregates the content of the dataset. This query returns a chart of the `avg(req_duration_ms)`, and a table of `geo.city` and `avg(req_duration_ms)` of the `sample-http-logs` dataset from the time range of 2 days and time interval of 4 hours.
```kusto
['sample-http-logs']
| where _time > ago(2d)
| summarize avg(req_duration_ms) by _time=bin(_time, 4h), ['geo.city']
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20where%20_time%20%3E%20ago\(2d\)%5Cn%7C%20summarize%20avg\(req_duration_ms\)%20by%20_time%3Dbin\(_time%2C%204h\)%2C%20%5B'geo.city'%5D%22%7D)
## Query results
The results view adapts to the query. This means that it adds and removes components as necessary to give you the best experience. The toolbar is always visible and gives details on the currently running or last-run query. The other components are explained below.
### Query results without visualizations
When you run a query on a dataset without specifying a visualization, Axiom displays a table with the raw query results.
#### View event details
To view the details for an event, click the event in the table.
To configure the event details view, select one of the following in the top right corner:
* Click 
**Navigate up** or 
**Navigate down** to display the details of the next or previous event.
* Click 
**Fit panel to results** or 
**Fit panel to viewport height** to change the height of the event details view.
#### Select displayed fields
To select the fields highlighted in the table, click 
, and then click the fields in the list. Axiom highlights the selected fields below the raw data for each event.
#### Configure table options
To configure the table options, click , and then select one of the following:
* Select **Wrap lines** to keep the whole table within the viewport and avoid horizontal scrolling.
* Select **Show timestamp** to display the time field.
* Clear the **Show event** checkbox to enter column mode. This means that the table displays each selected field in a different column and doesn’t show the raw event data. In column mode, you can resize the width of columns by dragging the borders.
* Select **Hide nulls** to hide empty data points.
#### Event timeline
Axiom can also display an event timeline about the distribution of events across the selected time range. In the event timeline, each bar represents the number of events matched within that specific time interval. Holding the pointer over a bar reveals a blue line marking the total events and shows when those events occurred in that particular time range. To display the event timeline, click , and then click **Show chart**.
### Query results with visualizations
When you run a query with visualizations, Axiom displays all the visualizations that you add to the query. Hold the pointer over charts to get extra detail on each result set.
Below the charts, Axiom displays a table with the totals from each of the aggregate functions for the visualizations you specify.
If the query includes group-by clauses, there is a row for each group. Hold the pointer over a group row to highlight the group’s data on time series charts. Select the checkboxes on the left to display data only for the selected rows.
#### Configure chart options
Click to access the following options for each chart:
* In **Values**, specify how to treat missing or undefined values.
* In **Variant**, specify the chart type. Select from area, bar, or line charts.
* In **Y-Axis**, specify the scale of the vertical axis. Select from linear or log scales.
* In **Annotations**, specify the types of annotations to display in the chart.
For more information on each option, see [Configure dashboard elements](/dashboard-elements/configure).
#### Merge charts
When you run a query that produces several visualizations, Axiom displays the charts separately. For example:
```kusto
['sample-http-logs']
| summarize percentiles_array(req_duration_ms, 50, 90, 95) by status, bin_auto(_time)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%5Cn%7C%20summarize%20percentiles_array\(req_duration_ms%2C%2050%2C%2090%2C%2095\)%20by%20status%2C%20bin_auto\(_time\)%22%7D)
To merge the separately displayed charts into a single chart, click , and then select **Merge charts**.
#### Compare time periods
On time series charts, holding the pointer over a specific time shows the same marker on similar charts for easy comparison.
When you run a query with a time series visualization, you can use the **Compare period** menu to select a historical time against which to compare the results of your time range. For example, to compare the last hour’s average response time to the same time yesterday, select `1 hr` in the time range menu, and then select `-1 day` from the **Compare period** menu. The dotted line represents results from the base date, and the totals table includes the comparative totals.
### Highlight time range
In the event timeline, line charts, and heat maps, you can drag the pointer over the chart to highlight a specific time range, and then choose one of the following:
* **Zoom** enlarges the section of the chart you highlighted.
* **Show events** displays events in the selected time range in the event details view.
The time range of your query automatically updates to match what you selected.
# Create dashboards with filters
This page explains how to create dashboards with filters that let you choose the data you want to display.
Filters let you choose the data you want to display in your dashboard. This page explains how to create and configure dashboards with filters.
Try out all the examples explained on this page in the [HTTP logs dashboard of the Axiom Playground](https://play.axiom.co/axiom-play-qf1k/dashboards/gZXp8KNJy68q7yGsuA).
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Send data](/send-data/ingest) to your Axiom dataset.
* [Create an empty dashboard](/dashboards/create).
## Filter types
You can use two types of filter in your dashboards:
* Search filters let you enter any text, filter for data that matches the text input, and then narrow down the results displayed by the charts in the dashboard. For example, you enter **Mac OS**, filter for results that contain this string in the user agent field, and then only display the corresponding results in the charts.
* Select filters let you choose one option from a list of options, filter for data that matches the chosen option, and then narrow down the results displayed by the charts in the dashboard. For example, you choose **France** from the list of countries, filter for results that match the chosen geographical origin, and then only display the corresponding results in the charts.
## Use dashboards with filters
To see different filters in action, check out the [HTTP logs dashboard of the Axiom Playground](https://play.axiom.co/axiom-play-qf1k/dashboards/gZXp8KNJy68q7yGsuA). The search filter on the top right lets you search for a specific phrase in the user agent field to only display HTTP requests from a specific user agent. The select filters on the top left let you choose country and city to only display HTTP requests from a specific geographical origin.
In each chart on your dashboard, you can use all, some, or none of the filters to narrow down the data displayed in the chart. For example, in the [HTTP logs dashboard of the Axiom Playground](https://play.axiom.co/axiom-play-qf1k/dashboards/gZXp8KNJy68q7yGsuA), the charts Popular data centers and Popular countries aren’t affected by your choices in the select filters. You choose to use a filter in a chart by [referencing the unique ID of the filter in the chart query](#reference-filters-in-chart-query) as explained later on this page.
Filters can be interdependent. For example, in the [HTTP logs dashboard of the Axiom Playground](https://play.axiom.co/axiom-play-qf1k/dashboards/gZXp8KNJy68q7yGsuA), the values you can choose in the city filter depend on your choice in the country filter. You make a filter dependent on another by [referencing the unique ID of the filter](#create-select-filters) as explained later on this page.
For each filter, you define a unique ID when you create the filter. When you create multiple filters, all of them must have a different ID. You can later use this ID to reference the filter in dashboard charts and other filters.
Filters are visually displayed in your dashboard in a filter bar that you can create and move as any other chart. You can add different types of filter to a single filter bar. A filter bar can contain maximum one search filter and any number of select filters.
## Create search filters
1. In the empty dashboard, click **Add element**.
2. In **Chart type**, select **Smart filter bar**.
3. In **Filter type**, select **Search**.
4. In **Filter name**, enter the placeholder text you want to display in your search filter.
5. Specify a unique filter ID that you later use to reference the filter. For example, `user_agent_filter`.
Try out this filter in the [HTTP logs dashboard of the Axiom Playground](https://play.axiom.co/axiom-play-qf1k/dashboards/gZXp8KNJy68q7yGsuA).
## Create select filters
1. In the empty dashboard, click **Add element**.
2. In **Chart type**, select **Smart filter bar**.
3. In **Filter type**, select **Select**.
4. In **Filter name**, enter the text you want to display above the select filter.
5. Specify a unique filter ID that you later use to reference the filter. For example, `country_filter`.
6. In the **Value** section, define the list of options to choose from in the select filter as key-value pairs. Axiom displays the key in the list of options in the filter dropdown, and uses the value to filter your data. For example, the key `France` is displayed in the list of options, and the value `FR` is used to filter data in your charts. Define the key-value pairs in one of the following ways:
* Choose **List** to manually define a static list of options. Enter the options as a list of key-value pairs.
* Choose **Query** to define a dynamic list of options. In this case, Axiom determines the list of options displayed in the filter dynamically based on an APL query. The results of the APL query must contain two fields which Axiom interprets as key-value pairs. Use the `project` command to create key-value fields from any output.
Select a dataset from the list of datasets to continue.
## Event stream
Upon selecting a dataset, you are immediately taken to the live event stream for that dataset:
You can click an event to be taken to the event details slide-out:
On this slide-out, you can copy individual field values, or copy the entire event as JSON.
You can view and copy the raw data:
## Filter data
The Stream tab provides access to a powerful filter builder right on the toolbar:
For more information, see the [filters documentation](/dashboard-elements/create#filters).
## Time range selection
The stream has two time modes:
* Live stream (default)
* Time range
Live stream continuously checks for new events and presents them in the stream.
Time range only shows events that fall between a specific start and end date. This can be useful when investigating an issue. THe time range menu has some options to quickly choose some time ranges, or you can input a specific range for your search:
When you are ready to return to live streaming, click this button:
Click the button again to pause the stream.
## View settings
The Stream tab is customizable via the view settings menu:
Options include:
* Text size used in the stream
* Wrap lines
* Highlight severity (this is automatically extracted from the event)
* Show the raw event details
* Fields to display in their own column
## Starred queries
The starred queries slide-out is activated via the toolbar:
For more information, see [Starred queries](/query-data/datasets#starred-queries).
## Highlight severity
The Stream tab enables you to process and inspect every log produced by your infrastructure, containers, and cloud environment. Highlighting severity allows you to track warning signs and detect errors from your resources and choose which logs to retain to maintain cost-efficiency.
On the settings view on the Stream tab, enabling **Highlight Severity** automatically searches for the words `warn` and `error` from the keys:
* `level`
* `severity`
* `@level`
* `@severity`
* `message`
* `msg`
* `@message`
* `text`
The `warn` value is displayed with color `orange`, and the `error` value is displayed with color `red`.
# Explore traces
Learn how to observe how requests propagate through your distributed systems, understand the interactions between microservices, and trace the life of the request through your app’s architecture.
Distributed tracing in Axiom allows you to observe how requests propagate through your distributed systems. This could involve a user request going through several microservices, and resources until the requested information is retrieved and returned. By tracing these requests, you’re able to understand the interactions between these microservices, pinpoint issues, understand latency, and trace the life of the request through your app’s architecture.
### Traces and spans
A trace is a representation of a single operation or transaction as it moves through a system. A trace is made up of multiple spans.
A span represents a logical unit of work in the system with a start and end time. For example, an HTTP request handling process might be a span. Each span includes metadata like unique identifiers (`trace_id` and `span_id`), start and end times, parent-child relationships with other spans, and optional events, logs, or other details to help describe the span’s operation.
### Trace schema overview
| Field | Type | Description |
| ---------------- | -------- | -------------------------------------------------------- |
| `trace_id` | String | Unique identifier for a trace |
| `span_id` | String | Unique identifier for a span within a trace |
| `parent_span_id` | String | Identifier of the parent span |
| `name` | String | Name of the span for example, the operation |
| `kind` | String | Type of the span (for example, client, server, producer) |
| `duration` | Timespan | Duration of the span |
| `error` | Boolean | Whether this span contains an error |
| `status.code` | String | Status of the span (for example, null, OK, error) |
| `status.message` | String | Status message of the span |
| `attributes` | Object | Key-value pairs providing additional metadata |
| `events` | Array | Timestamped events associated with the span |
| `links` | Array | Links to related spans or external resources |
| `resource` | Object | Information about the source of the span |
This guide explains how you can use Axiom to analyze and interrogate your trace data from simple overviews to complex queries.
## Browse traces with the OpenTelemetry app
The Axiom OpenTelemetry app automatically detects any OpenTelemetry trace data flowing into your datasets and publishes an OpenTelemetry Traces dashboard to help you browse your trace data.
### Navigate the app
* Use the **Filter Bar** at the top of the app to narrow the charts to a specific service or operation.
* Use the **Search Input** to find a trace ID in the selected time period.
* Use the **Slowest Operations** chart to identify performance issues across services and traces.
* Use the **Top Errors** list to quickly identify the worst-offending causes of errors.
* Use the **Results** table to get an overview and navigate between services, operations, and traces.
### View a trace
Click a trace ID in the results table to show the waterfall view. This view allows you to see that span in the context of the entire trace from start to finish.
### Customize the app
To customize the app, use the fork button to create an editable duplicate for you and your team.
## Query traces
In Axiom, trace events are just like any other events inside datasets. This means they’re directly queryable in the UI. While this is can be a powerful experience, it’s important to note some important details to consider before querying:
* Directly aggregating upon the `duration` field produces aggregate values across every span in the dataset. This is usually not the desired outcome when you want to inspect a service’s performance or robustness.
* For request, rate, and duration aggregations, it’s best to only include the root span using `isnull(parent_span_id)`.
## Waterfall view of traces
To see how spans in a trace are related to each other, explore the trace in a waterfall view. In this view, each span in the trace is correlated with its parent and child spans.
To explore spans within a trace using the OpenTelemetry Traces app, follow these steps:
1. Click the `Dashboards` tab.
2. Click `OpenTelemetry Traces`.
3. In the `Slowest Operations` chart, click the service that contains the trace.
4. In the list of trace IDs, click the trace you want to explore.
5. Explore how spans within the trace are related to each other in the waterfall view. To reveal additional options such as collapsing and expanding child spans, right-click a span.
To try out this example, go to the Axiom Playground.
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/dashboards/otel.traces.otel-demo-traces)
To access the waterfall view from the Query tab, follow these steps:
1. Ensure the dataset you work with has trace data.
2. Click the Query tab.
3. Run a query that returns the `_time` and `trace_id` fields. For example, the following query returns the number of spans in each trace:
```kusto
['otel-demo-traces']
| summarize count() by trace_id
```
4. In the list of trace IDs, click the trace you want to explore. To reveal additional options such as copying the trace ID, right-click a trace.
5. Explore how spans within the trace are related to each other in the waterfall view. To reveal additional options such as collapsing and expanding child spans, right-click a span. Event names are displayed on the timeline for each span.
To try out this example, go to the Axiom Playground.
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%5Cn%7C%20summarize%20count\(\)%20by%20trace_id%22%7D)
### Span duration histogram
In the waterfall view of traces, Axiom warns you about slow and fast spans. These spans are outliers because they’re at least a standard deviation over or under the average duration of spans that have the same span name and service name. Hold the pointer over the **SLOW** or **FAST** label to see additional information about the span type such as average and maximum duration. In addition, Axiom displays a histogram about the durations of spans that have the same span name and service name as the span you selected. By default, the histogram shows a one-hour window around the selected span.
The span duration histogram can be useful in the following cases, among others:
* You look at a span and you’re not familiar with the typical behavior of the service that created it. You want to know if you look at something normal in terms of duration or an outlier. The histogram helps you determine if you look at an outlier and might drill down further.
* You've found an outlier. You want to investigate and look at other outliers. The histogram shows you what the baseline is and what’s not normal in terms of duration. You want to filter for the outliers and see what they have in common.
* You want to see if there was a recent change in the typical duration for the selected span type.
To narrow the time range of the histogram, click and select an area in the histogram.
## Example queries
Below are a collection of queries that can help get you started with traces inside Axiom. Queries are all executable on the [Axiom Play sandbox](https://axiom.co/play).
Number of requests, average response
```kusto
['otel-demo-traces']
| where isnull(parent_span_id)
| summarize count(),
avg(duration),
percentiles_array(duration, 95, 99, 99.9)
by bin_auto(_time)
```
Top five slowest services by operation
```kusto
['otel-demo-traces']
| summarize count(), avg(duration) by name
| sort by avg_duration desc
| limit 5
```
Top five errors per service and operation
```kusto
['otel-demo-traces']
| summarize topk(['status.message'], 5) by ['service.name'], name
| limit 5
```
## Semantic Conventions
OpenTelemetry defines [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) which specify standard attribute names and values for different kinds of operations and data. Attributes that follow semantic conventions will be available as nested fields under the `attributes` field, such as `attributes.http.method`, `attributes.db.system`, etc.
For example, if a span represents an HTTP request, it may include the following attributes:
* `attributes.http.method`: The HTTP request method. For example, `GET`, `POST`, etc.
* `attributes.http.url`: The full HTTP request URL.
* `attributes.http.status_code`: The HTTP response status code.
Similarly, resource attributes that follow semantic conventions are available under the `resource` field, such as `resource.host.name`, `resource.host.id`, `resource.host.os`, etc.
Custom attributes that don’t match any semantic conventions are nested under the `attributes.custom` map field.
## Querying custom attributes
Trace spans often include many custom attributes under the `attributes.custom` field. These custom attributes are stored as nested key-value pairs.
To access nested custom attributes, you can use Axiom Processing Language (APL) for example:
```kusto
['otel-demo-traces']
| where ['attributes.custom']['app.synthetic_request'] == true
```
If you frequently need to query the same nested attribute, consider creating a virtual field for it:
1. Go to "Datasets" and click the f(x) button
2. Define the new virtual field, for example:
```kusto
['otel-demo-traces']
| extend useragent = ['attributes.custom']['User-Agent']
```
3. You can then query the virtual field like any other field in the UI or APL.
To create a typed virtual field, you can specify the type, e.g.:
```kusto
| extend deployment_id = tostring(['attributes.custom']['deployment_id'])
```
## Span links
Span links allow you to associate one span with one or more other spans, establishing a relationship between them that indicates the operation of one span depends on the other. Span links can connect spans within the same trace or across different traces.
Span links are useful for representing asynchronous operations or batch-processing scenarios. For example, an initial operation triggers a subsequent operation, but the subsequent operation may start at some unknown later time or even in a different trace. By linking the spans, you can capture and preserve the relationship between these operations, even if they’re not directly connected in the same trace.
### How it works
Span links in Axiom are based on the [OpenTelemetry specification](https://opentelemetry.io/docs/concepts/signals/traces/#span-links). When instrumenting your code, you create span links using the OpenTelemetry API by passing the `SpanContext` (containing `trace_id` and `span_id`) of the span to which to link. Links are specified when starting a new span by providing them in the span configuration. The OpenTelemetry SDK includes the link information when exporting spans to Axiom. Links are recorded at span creation time so that sampling decisions can consider them.
### View span links
1. Run the following APL query to find traces with span links, for example:
```kusto
['dataset']
| where isnotempty(links)
```
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7B%22apl%22%3A%20%22%5B%27otel-demo-traces%27%5D%5Cn%7C%20where%20isnotempty%28links%29%22%7D)
2. Click on a trace in the results and select the `trace_id`.
3. In the trace details view, find the links section. This displays the `trace_id` and `span_id` associated with each linked span, as well as other attributes of the link.
4. Click **View span** to navigate to a linked span, either in the same trace or a different trace.
# Virtual fields
Virtual fields allow you to derive new values from your data in real time, eliminating the need for up-front data structuring, enhancing flexibility and efficiency.
Virtual fields allow you to derive new values from your data in real time.
One of the most powerful features of Axiom are virtual fields. With virtual fields, there is no need to do any up-front planning of how to structure or transform your data. Instead, send your data as-is and then use virtual fields to manipulate your data in real-time during queries.
The feature is also known as derived fields, but Axiom’s virtual fields have some unique properties that make them much more powerful.
In this guide, you’ll be introduced to virtual fields, their features, how to manage them, and how to get the best out of them.
## Creating a virtual field
To create a virtual field, follow these steps:
1. Go to the Datasets tab.
2. Select the dataset where you want to create the virtual field.
3. Click the **Virtual fields** icon in the top right. You see a list of all the virtual fields for the dataset.
4. Click **Add virtual field**.
5. Fill in the following fields:
* **Name** and **Description** help your team understand what the virtual field is about.
* **Expression** is the formula applied to every event to calculate the virtual field. The expression produces a result such as a `boolean`, `string`, `number`, or `object`.
The **Preview** section displays the result of applying the expression to some of your data. Use this section to verify the expression and the resulting values of the virtual field.
The power of virtual fields is in letting you manipulate data on read instead of on write, allowing you to adjust and update virtual fields over time as well as easily add new ones without worrying that the data has already been indexed.
## Usage
### Visualizations
Virtual fields are available as parameters to visualizations but, as the type of a virtual field can be any of the supported types, it’s important to make sure that you use a virtual field that produces the correct type of argument.
### Filters
Virtual fields are available in the filter menu and all filter options are presented. It’s important to ensure that you are using a supported filter operation for the type of result your virtual field produces.
## Group By
Virtual fields can be used for segmentation in the same way as any standard field.
## Reference
Virtual fields are APL expressions and share all the same functions and syntax as APL expressions. For more information, see [Introduction to APL](/apl/introduction).
The list of APL scalar functions:
* [String functions](/apl/scalar-functions/string-functions)
* [Math functions](/apl/scalar-functions/mathematical-functions)
* [Array functions](/apl/scalar-functions/array-functions)
* [Conversion functions](/apl/scalar-functions/conversion-functions)
* [Hash functions](/apl/scalar-functions/hash-functions)
* [DateTime/Timespan functions](/apl/scalar-functions/datetime-functions)
* [Rounding functions](/apl/scalar-functions/rounding-functions)
* [Conditional functions](/apl/scalar-functions/conditional-function)
* [IP functions](/apl/scalar-functions/ip-functions)
`not ("us-east-1" contains "us")`
Use parenthesis because the operator `not` has precedence over the operator `contains`.
`myArray[1:5] == [2, 3, 4] myArray[3:] == [4, 5] myArray[:4] == [1, 2, 3] myArray[:] == myArray`
## `distinct`
The `distinct` visualization counts each distinct occurrence of the distinct field inside the dataset and produce a time series chart.
#### Arguments
`field: any` is the field to aggregate.
#### Group-By Behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `avg`
The `avg` visualization averages the values of the field inside the dataset and produces a time series chart.
#### Arguments
`field: number` is the number field to average.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `max`
The `max` visualization finds the maximum value of the field inside the dataset and produces a time series chart.
#### Arguments
`field: number` is the number field where Axiom finds the maximum value.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `min`
The `min` visualization finds the minimum value of the field inside the dataset and produces a time series chart.
#### Arguments
`field: number` is the number field where Axiom finds the minimum value.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `sum`
The `sum` visualization adds all the values of the field inside the dataset and produces a time series chart.
#### Arguments
`field: number` is the number field where Axiom calculates the sum.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `percentiles`
The `percentiles` visualization calculates the requested percentiles of the field in the dataset and produces a time series chart.
#### Arguments
* `field: number` is the number field where Axiom calculates the percentiles.
* `percentiles: number [, ...]` is a list of percentiles , each a float between 0 and 100. For example, `percentiles(request_size, 95, 99, 99.9)`.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a horizontal bar chart, allowing for visual comparison across the groups.
## `histogram`
The `histogram` visualization buckets the field into a distribution of N buckets, returning a time series heatmap chart.
#### Arguments
* `field: number` is the number field where Axiom calculates the distribution.
* `nBuckets` is the number of buckets to return. For example, `histogram(request_size, 15)`.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series histogram. Hovering over a group in the totals table shows only the results for that group in the histogram.
## `topk`
The `topk` visualization calculates the top values for a field in a dataset.
#### Arguments
* `field: number` is the number field where Axiom calculates the top values.
* `nResults` is the number of top values to return. For example, `topk(method, 10)`.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `variance`
The `variance` visualization calculates the variance of the field in the dataset and produces a time series chart.
The `variance` aggregation returns the sample variance of the fields of the dataset.
#### Arguments
`field: number` is the number field where Axiom calculates the variance.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
## `stddev`
The `stddev` visualization calculates the standard deviation of the field in the dataset and produces a time series chart.
The `stddev` aggregation returns the sample standard deviation of the fields of the dataset.
#### Arguments
`field: number` is the number field where Axiom calculates the standard deviation.
#### Group-by behaviour
The visualization produces a separate result for each group plotted on a time series chart.
# Track activity in Axiom
This page explains how to track activity in your Axiom organization with the audit log.
The audit log allows you to track who did what and when within your Axiom organization.
Tracking activity in your Axiom organization with the audit log is useful for legal compliance reasons. For example, you can investigate the following:
* Track who has accessed the Axiom platform.
* Track organization access over time.
* Track data access over time.
The audit log also make it easier to manage your Axiom organization. They allow you to do the following, among others:
* Track changes made by your team to your observability posture.
* Track monitoring performance.
The audit log is available to all users. Enterprise customers can query the audit log for the full time range. Other customers can query the audit log for the previous three days.
## Explore audit log
1. Go to the Query tab, and then click **APL**.
2. Query the `axiom-audit` dataset. For example, run the query `['axiom-audit']` to display the raw audit log data in a table.
3. Optional: Customize your query to filter or summarize the audit log. For more information, see [Explore data](/query-data/explore).
4. Click **Run**.
The `action` field specifies the type of activity that happened in your Axiom organization.
## Export audit log
1. Run the query to [display the audit log](#explore-audit-logs).
2. Click **More > Download as JSON**.
## Restrict access to audit log
To restrict access to the audit log, use Axiom’s role-based access control to define who can access the `axiom-audit` dataset. For more information, see [Access](/reference/settings#access-overview).
# Axiom CLI
Learn how to use the Axiom CLI to ingest data, manage authentication state, and configure multiple deployments.
Axiom’s command line interface (CLI) is an Axiom tool that lets you test, manage, and build your Axiom projects by typing commands on the command-line.
You can use the command line to Ingest data, manage authentication state, and configure multiple organizations.
## Installation
### Install using go install
To install Axiom CLI, make sure you have [Go](https://golang.org/dl/) version 1.16 or higher, then run this command from any directory in your terminal.
```bash
go install github.com/axiomhq/cli/cmd/axiom@latest
```
### Install using Homebrew
You can also install the CLI using [Homebrew](https://brew.sh/)
```bash
brew tap axiomhq/tap
brew install axiom
```
This installs Axiom command globally so you can run `axiom` commands from any directory.
To update:
```bash
brew upgrade axiom
```
### Install from source
```bash
git clone https://github.com/axiomhq/cli.git
cd cli
make install # Build and install binary into $GOPATH
```
### Run the Docker image
Docker images are available on [DockerHub.](https://hub.docker.com/r/axiomhq/cli)
```bash
docker pull axiomhq/cli
docker run axiomhq/cli
```
You can check the version and find out basic commands about Axiom CLI by running the following command:
```bash
axiom
```
## Authentication
The easiest way to start using Axiom CLI is by logging in through the command line. Simply run `axiom auth login` or simply `axiom` if no prior configuration exists. This will guide you through a straightforward login process.
## Managing multiple organizations
While most users will only need to manage a single Axiom deployment, Axiom CLI provides the capability to switch between multiple organizations for those who require it. You can easily switch between organizations using straightforward CLI commands. For example, `axiom auth switch-org` lets you change your active organization, or you can set the `AXIOM_ORG_ID` environment variable for the same purpose.
Every setting in Axiom CLI can be overwritten via environment variables configured in the `~/.axiom.toml` file. Specifically, `AXIOM_URL`, `AXIOM_TOKEN`, and `AXIOM_ORG_ID` are important for configuring your environment. The `AXIOM_URL` should be set to `https://api.axiom.co`. You can switch between environments using the `axiom auth select` command.
To view available environment variables, run `axiom help environment` for an up to date list of env vars:
```
AXIOM_DEPLOYMENT: The deployment to use. Overwrites the choice loaded
from the configuration file.
AXIOM_ORG_ID: The organization ID of the organization the access
token is valid for.
AXIOM_PAGER, PAGER (in order of precedence): A terminal paging
program to send standard output to, for example, "less".
AXIOM_TOKEN: Token The access token to use. Overwrites the choice
loaded from the configuration file.
AXIOM_URL: The deployment url to use. Overwrites the choice loaded
from the configuration file.
VISUAL, EDITOR (in order of precedence): The editor to use for
authoring text.
NO_COLOR: Set to any value to avoid printing ANSI escape sequences
for color output.
CLICOLOR: Set to "0" to disable printing ANSI colors in output.
CLICOLOR_FORCE: Set to a value other than "0" to keep ANSI colors in
output even when the output is piped.
```
## One-Click Login
The One-Click Login is an easier way to authenticate Axiom-CLI and log in to your Axiom deployments and account resources directly on your terminal using the Axiom CLI.
## Tokens
You can generate an ingest and personal token manually in your Axiom user settings.
See [Tokens](/reference/tokens) to know more about managing access and authorization.
## Configuration and Deployment
Axiom CLI lets you ingest, authenticate, and stream data.
For more information about Configuration, managing authentication status, ingesting, streaming, and more,
visit the [Axiom CLI](https://github.com/axiomhq/cli) repository on GitHub.
Axiom CLI supports the ingestion of different formats of data **( JSON, NDJSON, and CSV)**
## Querying
Get deeper insights into your data using [Axiom Processing Language](/apl/introduction)
## Ingestion
Import, transfer, load and process data for later use or storage using the Axiom CLI. With [Axiom CLI](https://github.com/axiomhq/cli) you can Ingest the contents of a **JSON, NDJSON, CSV** logfile into a dataset.
**To view a list of all the available commands run `axiom` on your terminal:**
```bash
➜ ~ axiom
The power of Axiom on the command-line.
USAGE
axiom **Settings > Datasets**.
2. Click **New dataset**.
3. Name the dataset, and then click **Add**.
Dataset names are 1 to 128 characters in length. They only contain ASCII alphanumeric characters and the hyphen (`-`) character.
## Import data
You can import data to your dataset in one of the following formats:
* Newline delimited JSON (NDJSON)
* Arrays of JSON objects
* CSV
To import data to a dataset, follow these steps:
1. Click **Settings > Datasets**.
2. In the list, click the dataset where you want to import data.
3. Click 
**Import**.
4. Optional: Specify the timestamp field. This is only necessary if your data contains a timestamp field and it’s different from `_time`.
5. Upload the file, and then click **Import**.
## Trim dataset
Trimming a dataset deletes all data in the dataset before a date you specify. This can be useful if your dataset contains too many fields or takes up too much storage space, and you want to reduce its size to ensure you stay within the [allowed limits](/reference/field-restrictions).
**Settings > Datasets**.
2. In the list, click the dataset that you want to trim.
3. Click 
**Trim dataset**.
4. Specify the date before which you want to delete data.
5. Enter the name of the dataset, and then click **Trim**.
## Vacuum fields
The data schema of your dataset is defined on read. Axiom continuously creates and updates the data structures during the data ingestion process. At the same time, Axiom only retains data for the [retention period defined by your pricing plan](/reference/field-restrictions). This means that the data schema can contain fields that you ingested into the dataset in the past, but these fields are no longer present in the data currently associated with the dataset. This can be an issue if the number of fields in the dataset exceeds the [allowed limits](/reference/field-restrictions).
In this case, vacuuming fields in a dataset can help you reduce the number of fields associated with a dataset and stay within the allowed limits. Vacuuming fields resets the number of fields associated with a dataset to the fields that occur in events within your retention period. Technically, it wipes the data schema and rebuilds it from the data you currently have in the dataset, which is partly defined by the retention period. For example, you have ingested 500 fields over the last year and 50 fields in the last 95 days, which is your retention period. In this case, before vacuuming, your data schema contains 500 fields. After vacuuming, the dataset only contains 50 fields.
Vacuuming fields doesn’t delete any events from your dataset. To delete events, [trim the dataset](#trim-dataset). You can use trimming and vacuuming in combination. For example, if you accidentally ingested events with fields you didn’t want to send to Axiom, and these events are within your retention period, vacuuming alone doesn’t solve your problem. In this case, first trim the dataset to delete the events with the unintended fields, and then vacuum the fields to rebuild the data schema.
**Settings > Datasets**.
2. In the list, click the dataset where you want to vacuum fields.
3. Click 
**Vacuum fields**.
4. Select the checkbox, and then click **Vacuum**.
## Delete dataset
**Settings > Datasets**.
2. In the list, click the dataset that you want to delete.
3. Click **Delete dataset**.
4. Enter the name of the dataset, and then click **Delete**.
## Change data retention period
The data retention period determines how long Axiom stores your data. By default, the data retention period is defined by your pricing plan and is the same for all datasets. You can configure custom retention periods for individual datasets. As a result, Axiom automatically trims data after the specified time period instead of the default one defined by your pricing plan. For example, this can be useful if your dataset contains sensitive event data that you don’t want to retain for a long time.
Custom retention periods can only be shorter than your pricing plan’s default retention period. If you need a longer retention period, consider changing your plan or contacting [Axiom’s Sales team](https://axiom.co/contact).
**Settings > Datasets**.
2. In the list, click the dataset for which you want to change the retention period.
3. Click 
**Edit dataset retention**.
4. Enter a data retention period. The custom retention period must be greater than 0 days and less than the default defined by your pricing plan.
5. Click **Submit**.
# EU domain
This page explains how to work with Axiom if your organization uses the EU domain.
If your organization uses the EU domain, the base domain of the Axiom app and the Axiom API reference is different from the US domain.
The examples in this documentation use the US domain. For this reason, if your organization use the EU domain, you need to make some changes to the examples you find in this documentation.
## Check your domain
To check which domain your organization uses, open the Axiom web app and check the URL in the browser:
* If the URL starts with `https://app.axiom.co/`, you use the default US domain.
* If the URL starts with `https://app.eu.axiom.co/`, you use the EU domain.
## Axiom app
If your organization uses the EU domain, the base domain is `https://app.eu.axiom.co/`. This is different from the default US domain `https://app.axiom.co/` you see everywhere in the documentation.
## Axiom API reference
All examples in the [Axiom API reference](/restapi/introduction) use the US domain `api.eu.axiom.co`.
If your organization uses the EU domain, change the base domain in the examples to `api.eu.axiom.co`.
# Limits and requirements
This reference article explains the pricing-based and system-wide limits and requirements imposed by Axiom.
Axiom applies certain limits and requirements to guarantee good service across the platform. Some of these limits depend on your pricing plan, and some of them are applied system-wide. This reference article explains all limits and requirements applied by Axiom.
Limits are necessary to prevent potential issues that could arise from the ingestion of excessively large events or data structures that are too complex. Limits help maintain system performance, allow for effective data processing, and manage resources effectively.
## Pricing-based limits
The table below summarizes the limits applied to each pricing plan. For more details on pricing and contact information, see the [Axiom pricing page](https://axiom.co/pricing).
| | Personal | Team | Enterprise |
| ---------------------- | --------------------------- | ------------------------------------------------------------------------------ | ---------- |
| Ingest (included) | 500 GB / month | 1 TB / month | Custom |
| Ingest (maximum) | 500 GB / month | 50 TB / month | Custom |
| Query-hours (included) | 10 GB-hours / month | 100 GB-hours / month | Custom |
| Retention | 30 days | 95 days | Custom |
| Datasets | 2 | 20 | Custom |
| Fields per dataset | 256 | 1024 | Custom |
| Monitors | 3 | 50 | Custom |
| Notifiers | Email, Discord | Email, Discord, Opsgenie,PagerDuty, Slack, Webhook,
Microsoft Teams | Custom | | Endpoints | 1 (Honeycomb, Loki, Splunk) | 5 (Honeycomb, Loki, Splunk, Syslog) | Custom | If you’re on the Team plan and you exceed the maximum ingest and query-hours quota outlined above, additional charges apply based on your usage above the quota. For more information, see the [Axiom pricing page](https://axiom.co/pricing). All plans include unlimited bandwidth, API access, and data sources subject to the [Fair Use Policy](https://axiom.co/terms). To see how much of your allowance each dataset uses, go to
**Settings > Usage**.
### Restrictions on datasets and fields
Axiom restricts the number of datasets and the number of fields in your datasets. The number of datasets and fields you can use is based on your pricing plan and explained in the table above.
If you ingest a new event that would exceed the allowed number of fields in a dataset, Axiom returns an error and rejects the event. To prevent this error, ensure that the number of fields in your events are within the allowed limits. To reduce the number of fields in a dataset, [trim the dataset](/reference/datasets#trim-dataset) and [vacuum its fields](/reference/datasets#vacuum-fields).
## System-wide limits
The following limits are applied to all accounts, irrespective of the pricing plan.
### Limits on ingested data
The table below summarizes the limits Axiom applies to each data ingest. These limits are independent of your pricing plan.
| | Limit |
| ------------------------- | --------- |
| Maximum event size | 1 MB |
| Maximum events in a batch | 10,000 |
| Maximum field name length | 200 bytes |
### Requirements of the timestamp field
The most important field requirement is about the timestamp.
### Assigning capabilities to roles
Role creation is split into organization-level and dataset-level capabilities. Each capability has options to assign create, read, update, or delete (CRUD) permissions.
Organization-level capabilities define access for various parts of an Axiom organization.
* **Access control**: Full CRUD.
* **API tokens**: Full CRUD.
* **Apps**: Full CRUD.
* **Billing**: Read and update only.
* **Dashboards**: Full CRUD.
* **Datasets**: Full CRUD.
* **Endpoints**: Full CRUD.
* **Monitors**: Full CRUD.
* **Notifiers**: Full CRUD.
* **Shared Access Key**: Read and update only.
* **Users**: Full CRUD.
Refer to the table below to learn more about these organization-level capabilities:
| Organization | Create | Read | Update | Delete |
| ------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Access control | User can create custom roles and groups. | User can view the list of existing roles and groups. | User can update the and description of roles and groups, and modify permissions. | User can delete custom roles or groups. |
| API tokens | User can create an API token with access to the datasets their user has access to. | User can access the list of tokens that have been in their organization. | User can regenerate a token from the list of tokens in an organization. | User can delete API tokens created in their organization. |
| Apps | User can create a new app. | Users can access the list of installed apps in their organization. | Users can modify the existing apps in their organization. | User can disconnect apps installed in their organization. |
| Billing | — | User can access billing settings. | User can change the organization plan. | — |
| Dashboards | User can create new dashboards. | User can access their own dashboards and those created by other users in their organization. | User can modify dashboard titles and descriptions. User can add, resize, and delete charts from dashboards. | User can delete a dashboard from their organization. |
| Datasets | User can create a new dataset. | Users can access the list of datasets in an organization, and their associated fields. | User can trim a dataset, and modify dataset fields. | User can delete a dataset from their organization. |
| Endpoints | User can create a new endpoint. | User can access the list of existing endpoints in an organization. | Users can rename an endpoint and modify which dataset data is ingested into. | User can delete an endpoint from their organization. |
| Monitors | User can create a monitor. | User can access the list of monitors in their organization. User can also review the monitor status. | Users can modify a monitor configuration in their organization. | Users can delete monitors that have been created in their organization. |
| Notifiers | User can create a new notifier in their organization. | User can access the list of notifiers in their organization. | User can update existing notifiers in their organization. User can snooze a notifier. | User can delete notifiers that have been created in their organization. |
| Users | Users can invite new users to an organization. | User can access the list of users that are part of their organization. | User can update user roles and information within the organization. | Users can remove other users from their organization and delete their own account. |
| Shared Access Keys | — | User can access shared access keys in their organization. | User can update shared access keys in their organization. | — |
Dataset-level capabilities provide fine-grained control over access to datasets. For flexibility, the following capabilities can be assigned for all datasets, or individual datasets.
* **Ingest:** Create only.
* **Query**: Read only.
* **Starred queries**: Full CRUD.
* **Virtual fields**: Full CRUD.
Refer to the table below to learn more about these dataset-level capabilities:
| Datasets | Create | Read | Update | Delete |
| --------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------- |
| Ingest | User can ingest events to the specified dataset(s). | — | — | — |
| Starred queries | User can create a starred query for the specified dataset(s). | User can access the list of starred queries in their organization. | User can modify an existing starred query in their organization. | User can delete a starred query from a dataset. |
| Virtual fields | User can create a new virtual field for the specified dataset(s). | User can see the list of virtual fields for the specified dataset(s). | User can modify the definition of a virtual field for the specified dataset(s). | User can delete a virtual field from a dataset. |
| Query | — | User can query events from the specified dataset(s). | — | — |
### Groups
Groups, which are available to Axiom organizations on the Enterprise plan, connect users with roles, making it easier to manage access control at scale.
Organizations might create groups for areas of their business like Security, Infrastructure, or Business Analytics, with specific roles assigned to serve the unique needs of these domains.
Since groups connect users with one or many roles, users' complete set of capabilities are derived from the additive union of their base role, plus any roles assigned through group membership.
### Creating a New Group
1. Navigate to Groups and select New group.
2. Enter the name and description of the group.
3. Add users to the group. Clicking on Add users will display a list of available users.
4. Add roles to the group by clicking Add roles, which will present a list of available roles.
### Users
Users in Axiom are the individual accounts that have access to an organization. Users are assigned a base role when joining an organization, which is configured during the invite step. For organizations on an Enterprise plan, additional roles can be added through Group membership.
### Managing Users
1. Navigate to Settings and select Users.
2. Review and manage the list of users and assign default or custom base roles as desired.
Access for a user is the additive union of capabilities assigned through their default role, plus any capabilities included in roles assigned through group membership.
## Data
### Apps
Enrich your Axiom organization with a catalogue of migrations tools, and dedicated apps, and gain complete visibility into any platform, and get alerts on your errors to stay ahead of issues.
By properly monitoring your apps with Axiom, you can spot slowdowns, hiccups, bad requests, errored requests, and function cache performance and know which actions to take to correct these issues before there are user-facing consequences.
[Check out supported Apps](/apps/introduction)
### Dataset
Manage datasets for your organization, including creating new datasets or deleting existing datasets.
Datasets are a collection of similar events. When data is sent to Axiom it is stored in a dataset.
Dataset names must be between 1-128 characters, and may only contain ASCII alphanumeric characters and the '-' character.
To create a dataset, enter the name and description of your dataset.
Once created, you can import files into your datasets in supported formats such as NDJSON, JSON, or CSV. Additionally, you have the options to trim the dataset and delete it as needed.
### Endpoints
Endpoints allow you to easily integrate Axiom into your existing data flow using tools and libraries that you already know. With Endpoints, you can build and configure your existing tooling to send data to Axiom so you can start monitoring your logs immediately.
## Organization
### Billing
Manage your project billing, view your current plan, and explore the total usage of each component during your current billing period up to the last hour.
You can upgrade your organization to a free 14-day trial. Axiom will not charge you during the first 14 days of your Axiom Pro trial. You can cancel at any time during the trial period without incurring any cost.
At the end of the trial period, your account will automatically convert to a paid plan.
On the Billings dashboard you can get the total usage of each running component during the current billing period up to the last hour and beyond.
### License
You can see the license and configurations for your organization by selecting License this lets you know:
* How much data you can ingest.
* Monthly ingest limit (GB).
* Maximum endpoints.
* Maximum datasets you can have.
* Maximum fields per dataset.
* Maximum monitors.
* Maximum number of Users.
* Maximum number of Teams.
* Maximum query window.
## Profile
In the Profile section, you can configure the following:
* Change your name.
* View your contact details and role.
* Change your timezone.
* Change the editor mode.
* Select the default method for null values. When you run a query with a visualization, you can select how Axiom treats null values in the chart options. For more information, see [Configure chart options](/query-data/explore#configure-chart-options). When you select a default method to deal with null values, Axiom uses this method in every new chart you create.
* View and manage your active sessions.
* Create and delete personal access tokens. For more information, see [Personal access tokens](/reference/tokens#personal-access-tokens-pat).
* Delete your account.
# Authenticate API requests with tokens
Learn how you can authenticate your requests to the Axiom API with tokens.
This reference article explains how you can authenticate your requests to the Axiom API with tokens.
## Why authenticate with tokens
You can use the Axiom API and CLI to programmatically ingest data and manage your organisation settings. For example, you can add new users and change existing monitors with API requests. To prove that these requests come from you, you must include forms of authentication called tokens in your API requests. Axiom offers two types of tokens:
* [API tokens](#api-tokens) let you control the actions that can be performed with the token. For example, you can specify that requests authenticated with a certain API token can only query data from a particular dataset.
* [Personal access tokens (PATs)](#personal-access-tokens-pat) provide full control over your Axiom account. Requests authenticated with a PAT can perform every action you can perform in Axiom.
**Settings > API tokens**, and then click **New API token**.
2. Name your API token.
3. Optional: Give a description to the API token and set an expiration date.
4. In **Token permissions**, click **Basic**.
5. In **Dataset access**, select the datasets where this token can ingest data.
6. Click **Create**.
7. Copy the API token that appears and store it securely. It won’t be displayed again.
### Create advanced API token
1. Click **Settings > API tokens**, and then click **New API token**.
2. Name your API token.
3. Optional: Give a description to the API token and set an expiration date.
4. In **Token permissions**, click **Advanced**.
5. Select the datasets that this token can access and the actions it can perform.
6. In **Org level permissions**, select the actions the token can perform that affect your whole Axiom organisation. For example, creating users and changing existing notifiers.
7. Click **Create**.
8. Copy the API token that appears and store it securely. It won’t be displayed again.
### Regenerate API token
Similarly to passwords, it’s recommended to change API tokens regularly and to set an expiration date after which the token becomes invalid. When a token expires, you can regenerate it.
To regenerate an advanced API token, follow these steps:
1. Click **Settings > API tokens**.
2. In the list, select the API token you want to regenerate.
3. Click **Regenerate token**.
4. Copy the regenerated API token that appears and store it securely. It won’t be displayed again.
5. Update all the API requests where you use the API token with the regenerated token.
### Delete API token
1. Click **Settings > API tokens**.
2. In the list, point your mouse over the API token you want to delete.
3. To the right, click **Delete**.
## Personal access tokens (PAT)
Personal access tokens (PATs) provide full control over your Axiom account. Requests authenticated with a PAT can perform every action you can perform in Axiom. When possible, avoid using PATs.
To authenticate an API request with a PAT, include the Org ID in the requests. For more information, see [Get started with Axiom API](/restapi/introduction).
### Create PAT
1. Click **Settings > Profile**.
2. In the **Personal tokens** section, click **New token**.
3. Name the PAT.
4. Optional: Give a description to the PAT.
5. Copy the PAT that appears and store it securely. It wont be displayed again.
### Delete PAT
1. Click **Settings > Profile**.
2. In the list, find the PAT that you want to delete.
3. To the right of the PAT, click **Delete**.
# API limits
Learn how to limit the number of calls a user can make over a certain period of time.
Axiom limits the number of calls a user (and their organization) can make over a certain period
of time to ensure fair usage and to maintain the quality of our service for everyone.
Our systems closely monitor API usage and if a user exceeds any thresholds, we will
temporarily halt further processing of requests from that user (and/or organization).
This is to prevent any single user or app from overloading the system,
which could potentially impact other users' experience.
## Rate Limits
Rate limits vary and are specified by the following header in all responses:
| Header | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Scope` | Indicates if the limits counts against the organisation or personal rate limit. |
| `X-RateLimit-Limit` | The maximum number of requests a user is permitted to make per minute. |
| `X-RateLimit-Remaining` | The number of requests remaining in the current rate limit window. |
| `X-RateLimit-Reset` | The time at which the current rate limit window resets in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time). |
**Possible values for X-RateLimit-Scope :**
* `user`
* `organization`
**When the rate limit is exceeded, an error is returned with the status "429 Too Many Requests"**:
```json
{
"message": "rate limit exceeded",
}
```
## Query Limits
| Header | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `X-QueryLimit-Limit` | The query cost limit of your plan in Gigabyte Milliseconds (GB\*ms). |
| `X-QueryLimit-Remaining` | The remaining query Gigabyte Milliseconds. |
| `X-QueryLimit-Reset` | The time at which the current rate limit window resets in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time). |
## Ingest Limits
| Header | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `X-IngestLimit-Limit` | The maximum bytes ingested a user is permitted to make per month. |
| `X-IngestLimit-Remaining` | The bytes ingested remaining in the current rate limit window. |
| `X-IngestLimit-Reset` | The time at which the current rate limit window resets in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time). |
Alongside data volume limits, we also monitor the rate of ingest requests.
If an organization consistently sends an excessive number of requests per second,
far exceeding normal usage patterns, we reserve the right to suspend their ingest
to maintain system stability and ensure fair resource allocation for all users.
To prevent exceeding these rate limits, it is highly recommended to use batching clients,
which can efficiently manage the number of requests by aggregating data before sending.
# Create annotation
v2 post /annotations
Create annotation
# Create dataset
v1 post /datasets
Create a dataset
# Create API token
v2 post /tokens
Create API token
# Delete annotation
v2 delete /annotations/{id}
Delete annotation
# Delete dataset
v1 delete /datasets/{id}
Delete dataset
# Delete API token
v2 delete /tokens/{id}
Delete API token
# Retrieve annotation
v2 get /annotations/{id}
Get annotation by ID
# List all annotations
v2 get /annotations
Get annotations
# Retrieve current user
v1 get /user
Get current user
# Retrieve dataset
v1 get /datasets/{id}
Retrieve dataset by ID
# List all datasets
v1 get /datasets
Get list of datasets available to the current user.
# Retrieve API token
v2 get /tokens/{id}
Get API token by ID
# List all API tokens
v2 get /tokens
Get API tokens
# Ingest data
v1 post /datasets/{id}/ingest
Ingest
# Run query
v1 post /datasets/_apl
Query
# Run query (legacy)
v1 post /datasets/{id}/query
Query (Legacy)
# Regenerate API token
v2 post /tokens/{id}/regenerate
Regenerate API token
# Trim dataset
v1 post /datasets/{id}/trim
Trim dataset
# Update annotation
v2 put /annotations/{id}
Update annotation
# Update dataset
v1 put /datasets/{id}
Update dataset
# Send data via Axiom API
Learn how to send and load data into Axiom using the API.
This API allows you to send and load data into Axiom. You can use different methods to ingest logs depending on your requirements and log format.
## Authorization and Headers
The only expected headers are the `Authorization: Bearer`, which is your API or personal token. Learn more about [API Token](/reference/tokens) and [Org ID](/restapi/introduction#organization-id).
## Using Axiom JS library to ingest data
Axiom maintains the [axiom-js](https://github.com/axiomhq/axiom-js) to provide official Javascript bindings for the Axiom API.
Install using `npm install`:
```shell
npm install @axiomhq/js
```
If you use the [Axiom CLI](https://github.com/axiomhq/cli), run `eval $(axiom config export -f)` to configure your environment variables.
Otherwise create a personal token in [the Axiom settings](https://app.axiom.co/profile) and export it as `AXIOM_TOKEN`. Set `AXIOM_ORG_ID` to the organization ID from the settings page of the organization you want to access.
You can also configure the client using options passed to the constructor of the Client:
```ts
const client = new Client({
token: process.env.AXIOM_TOKEN,
orgId: process.env.AXIOM_ORG_ID,
});
```
Create and use a client like this:
```ts
import { Axiom } from '@axiomhq/js';
async function main() {
const axiom = new Axiom({
token: process.env.AXIOM_TOKEN,
orgId: process.env.AXIOM_ORG_ID,
});
await axiom.ingest('my-dataset', [{ foo: 'bar' }]);
const res = await axiom.query(`['my-dataset'] | where foo == 'bar' | limit 100`);
}
```
These examples send an API event to Axiom. Before getting started with Axiom API, you need to create a [Dataset](/reference/datasets) and [API Token](/reference/tokens).
## Ingest Events using JSON
The following example request contains grouped events. The structure of the `JSON` payload should have the scheme of `[ { "labels": { "key1": "value1", "key2": "value12" } }, ]`, in which the array comprises of one or more JSON objects describing Events.
### Example Request using JSON
```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-d '[
{
"time":"2021-23-04302:11:23.222Z",
"data":{"key1":"value1","key2":"value2"}
},
{
"data":{"key3":"value3"},
"labels":{"key4":"value4"}
}
]'
```
### Example Response
A successful POST Request returns a `200` response code JSON with details:
```json
{
"ingested": 2,
"failed": 0,
"failures": [],
"processedBytes": 219,
"blocksCreated": 0,
"walLength": 8
}
```
### Example Request using Nested Arrays
```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-d '[
{
"axiom": [{
"logging":[{
"observability":[{
"location":[{
"credentials":[{
"datasets":[{
"first_name":"axiom",
"last_name":"logging",
"location":"global"
}],
"work":[{
"details":"https://app.axiom.co/",
"tutorials":"https://www.axiom.co/blog",
"changelog":"https://www.axiom.co/changelog",
"documentation": "https://www.axiom.co/docs"
}]
}],
"social_media":[{
"details":[{
"twitter":"https://twitter.com/AxiomFM",
"linkedin":"https://linkedin.com/company/axiomhq",
"github":"https://github.com/axiomhq"
}],
"features":[{
"datasets":"view logs",
"stream":"live_tail",
"explorer":"queries"
}]
}]
}]
}],
"logs":[{
"apl": "functions"
}]
}],
"storage":[{}]
}]}
]'
```
### Example Response
A successful POST Request returns a `200` response code JSON with details:
```json
{
"ingested":1,
"failed":0,
"failures":[],
"processedBytes":1509,
"blocksCreated":0,
"walLength":6
}
```
### Example Request using Objects, Strings, and Arrays
```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-d '[{ "axiom": {
"logging": {
"observability": [
{ "apl": 23, "function": "tostring" },
{ "apl": 24, "operator": "summarize" }
],
"axiom": [
{ "stream": "livetail", "datasets": [4, 0, 16], "logging": "observability", "metrics": 8, "dashboard": 10, "alerting": "kubernetes" }
]
},
"apl": {
"reference":
[[80, 12], [30, 40]]
}
}
}]'
```
### Example Response
A successful POST Request returns a `200` response code JSON with details:
```json
{
"ingested":1,
"failed":0,
"failures":[],
"processedBytes":432,
"blocksCreated":0,
"walLength":7
}
```
### Example Response
A successful POST Request returns a `200` response code JSON with details:
```json
{
"ingested": 6,
"failed": 0,
"failures": [],
"processedBytes": 236,
"blocksCreated": 0,
"walLength": 6
}
```
## Ingest Events using CSV
The following example request contains events. The structure of the `CSV` payload uses a comma to separate values `'value1, value2, value3'`.
### Example Request using CSV
```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: text/csv' \
-d 'user, name
foo, bar'
```
### Example Response
A successful POST Request returns a 200 response code JSON with details:
```json
{
"ingested": 1,
"failed": 0,
"failures": [],
"processedBytes": 28,
"blocksCreated": 0,
"walLength": 2
}
```
Datasets names are usually case sensitive, Dataset names must be between 1-128 characters, and may only contain ASCII alphanumeric characters and the '-' character.
# Get Started with Axiom API
Learn how to ingest structured data logs, handle queries, and manage your deployments using the API.
Axiom understands your resources and provides an API to ingest structured data logs, handle queries, and manage your deployments. This REST-style API uses JSON for serialization and gives you complete control over the entire Axiom platform.
This page covers the basics for interacting with the Axiom API, instructions for ingesting data, and notes on some commonly used endpoints.
You can use the API commands with `curl` by providing your [Access Token](/reference/tokens).
## API Basics
All our endpoints live under the url `https://api.axiom.co` and follow the REST architectural style.
Here’s an example in **curl**:
```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-d '[
{
"axiom": "logging"
}
]'
```
## Content Type
All requests must be encoded as JSON with the `Content-Type` header set to `application/json`. If not otherwise specified, responses from the Axiom API, including errors, are encoded exclusively as JSON as well.
## Datasets
Datasets are required to send, query, and retrieve requests. Datasets are a collection of similar events. When data is sent to Axiom, it is stored in a dataset.
You will need to create or use an existing Dataset to get started with Axiom REST API.
See [Creating a Dataset](/reference/datasets) to get started.
## Authentication
Requests to the Axiom API must provide an API token through the `Authorization` header:
```bash
Authorization: Bearer <$API_TOKEN or $PERSONAL_TOKEN>
```
The `Authorization` header with an access token:
API Tokens can be created and managed from **Settings --> API Tokens** on Axiom UI.
See [Access Tokens](/reference/tokens) for more detail.
## Organization ID
Organization identification is required for you to send requests using [Personal Tokens](/reference/tokens#personal-access-tokens-pat).
The `org id` credentials can be obtained on the **Settings** page.
The `org id` can also be obtained from the `url` of your Axiom deployment.
In your Axiom deployment url `https://app.axiom.co/axiom-wt8j/datasets`, the credential `axiom-wt8j` is the organization ID.
## Failed Authentication
If authentication is unsuccessful for a request, the error status code `403` is returned.
## Types
Below is a list of the types of data used within the Axiom API:
| Name | Definition | Example |
| ----------- | ----------------------------------------------------------------- | ----------------------- |
| **ID** | A unique value used to identify resources. | "io12h34io1h24i" |
| **String** | A sequence of characters used to represent text. | "string value" |
| **Boolean** | A type of two possible values representing true or false. | true |
| **Integer** | A number without decimals. | 4567 |
| **Float** | A number with decimals. | 15.67 |
| **Map** | A data structure with a list of values assigned to a unique key. | \{ "key": "value" } |
| **List** | A data structure with only a list of values separated by a comma. | \["value", 4567, 45.67] |
## EU domain
All examples in the Axiom API reference use the US domain `api.eu.axiom.co`.
If your oprganization uses the EU domain, change the base domain in the examples to `api.eu.axiom.co`.
# Pagination in Axiom API
Learn how to use pagination with the Axiom API.
Pagination allows you to retrieve responses in manageable chunks.
You can use pagination for the following endpoints:
* [Run Query](/restapi/endpoints/queryApl)
* [Run Query (Legacy)](/restapi/endpoints/queryDataset)
## Pagination mechanism
Axiom uses cursor-based pagination for these endpoints. The parameters and mechanisms differ between the current and legacy endpoints.
### Run Query
To use pagination with the Run Query endpoint:
* Include the [`limit` operator](/apl/tabular-operators/limit-operator) in the APL query of your API request. The argument of this operator determines the number of events to display per page.
* Use `sort by _time asc` or `sort by _time desc` in the APL query. This returns the results in ascending or descending chronological order. For more information, see [sort operator](/apl/tabular-operators/sort-operator).
* Specify `startTime` and `endTime` in the body of your API request.
### Run Query (Legacy)
To use pagination with the legacy Run Query endpoint:
* Add the `limit` parameter to the body of your API request. The value of this parameter determines the number of events to display per page.
* Add the `order` parameter to the body of your API request. In the value of this parameter, order the results by time in either ascending or descending chronological order. For example, `[{ "field": "_time", "desc": true }]`. For more information, see [order operator](/apl/tabular-operators/order-operator).
* Specify `startTime` and `endTime` in the body of your API request.
## Response format
Use the Axiom Lambda Extension to send logs and platform events of your Lambda function to Axiom.
Alternatively, you can use the AWS Distro for OpenTelemetry to send Lambda function logs and platform events to Axiom. For more information, see [AWS Lambda Using OTel](/send-data/aws-lambda-dot).
Axiom detects the extension and provides you with quick filters and a dashboard. For more information on how this enriches your Axiom organization, see [AWS Lambda app](/apps/lambda).
To determine the best method to send data from different AWS services, see [Send data from AWS to Axiom](/send-data/aws-overview).
[AWS S3 Forwarder](/send-data/aws-s3)
[Amazon Data Firehose](/send-data/aws-firehose) | | Amazon CloudFront | [AWS S3 Forwarder](/send-data/aws-s3) | | Amazon Data Firehose | [Amazon Data Firehose](/send-data/aws-firehose) | | Amazon Elastic Container Service | [Fluentbit](/send-data/fluent-bit) | | Amazon Elastic Load Balancing (ELB) | [Fluentbit](/send-data/fluent-bit) | | Amazon ElastiCache (Redis OSS) | [Axiom CloudWatch Forwarder](/send-data/cloudwatch)
[Amazon Data Firehose](/send-data/aws-firehose) | | Amazon EventBridge Pipes | [Axiom CloudWatch Forwarder](/send-data/cloudwatch)
[AWS S3 Forwarder](/send-data/aws-s3)
[Amazon Data Firehose](/send-data/aws-firehose) | | Amazon FinSpace | [Axiom CloudWatch Forwarder](/send-data/cloudwatch)
[AWS S3 Forwarder](/send-data/aws-s3)
[Amazon Data Firehose](/send-data/aws-firehose) | | Amazon S3 | [AWS S3 Forwarder](/send-data/aws-s3)
[Vector](/send-data/vector) | | Amazon Virtual Private Cloud (VPC) | [AWS S3 Forwarder](/send-data/aws-s3) | | AWS Fault Injection Service | [AWS S3 Forwarder](/send-data/aws-s3) | | AWS FireLens | [AWS FireLens](/send-data/aws-firelens) | | AWS Global Accelerator | [AWS S3 Forwarder](/send-data/aws-s3) | | AWS IoT Core | [AWS IoT](/send-data/aws-iot-rules) | | AWS Lambda | [AWS Lambda](/send-data/aws-lambda) |
2. Configure the destination:
* **Name:** Choose a name for the destination.
* In the Axiom UI, click the Datasets tab and create your dataset by entering its name and description.
* **Endpoint URL:** Input the URL of your Axiom log ingest endpoint. This should be something like `https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest`. Replace `$DATASET_NAME` with the name of your dataset.
* **Method:** Choose `POST`.
* **Event Breaker:** Set this to One Event Per Request or CRLF (Carriage Return Line Feed), depending on how you want to separate events.
3. Headers:
You may need to add some headers. Here is a common example:
* **Content-Type:** Set this to `application/json`.
* **Authorization:** This should be `Bearer $API_Token`, replacing `$API_Token` with the actual API token from [organization settings](/reference/tokens).
4. Body:
In the Body Template, input `{{_raw}}`. This forwards the raw log event to Axiom.
5. Save and enable the destination:
After you've finished configuring the destination, save your changes and make sure the destination is enabled.
## Set up log forwarding from Cribl to Axiom using the Syslog destination
### Create Syslog endpoint
1. Click **Settings > Endpoints**.
2. Click **New endpoint**.
3. Click **{endpointName_0}**.
4. Name the endpoint.
5. Select the dataset where you want to send data.
6. Copy the URL displayed for the newly created endpoint. This is the target URL where you send the data.
### Configure destination in Cribl
1. Create a new Syslog destination in Cribl LogStream:
Open Cribl’s UI and navigate to **Destinations > Syslog**. Click on `+` Add New to create a new destination.
2. Configure the destination:
* **Name:** Choose a name and output ID for the destination.
* **Protocol:** Choose the protocol for the Syslog messages. Select the TCP protocol.
* **Destination Address:** Input the address of the Axiom endpoint to which you want to send logs. This address is generated from your Syslog endpoint in Axiom and follows this format: `tcp+tls://qsfgsfhjsfkbx9.syslog.axiom.co:6514`.
* **Destination Port:** Enter the port number on which the Axiom endpoint is listening for Syslog messages which is `6514`
* **Format:** Choose the Syslog message format. `RFC3164` is a common format and is generally recommended.
* **Facility:** Choose the facility code to use in the Syslog messages. The facility code represents the type of process that’s generating the Syslog messages.
* **Severity:** Choose the severity level to use in the Syslog messages. The severity level represents the importance of the Syslog messages.
3. Configure the Message:
* **Timestamp Format:** Choose the timestamp format to use in the Syslog messages.
* **Application Name Field:** Enter the name of the field to use as the app name in the Syslog messages.
* **Message Field:** Enter the name of the field to use as the message in the Syslog messages. Typically, this would be `_raw`.
* **Throttling:** Enter the throttling value. Throttling is a mechanism to control the data flow rate from the source (Cribl) to the destination (in this case, an Axiom Syslog Endpoint).
4. Save and enable the destination
After you've finished configuring the destination, save your changes and make sure the destination is enabled.
# Send data from Datadog to Axiom
Send data from Datadog to Axiom.
Sending data from Datadog to Axiom is a private preview feature available upon request.
Please [contact Axiom](https://axiom.co/migrations/datadog) to learn more about sending data from Datadog to Axiom.
# Send data
Use Axiom’s API to ingest, transport, and retrieve data from different sources such as relational databases, web logs, app logs, and kubernetes.
Send (ingest), transport, and fetch data from different sources such as Relational database, web logs, batch data, real-time, app logs, streaming data, etc. for later usage with the Axiom API.
You can also collect, load, group, and move data from one or more sources to Axiom where it can be stored and further analyzed.
Before ingesting data, you need to generate an API token from the **Settings > Tokens** page on the Axiom Dashboard. See [API tokens documentation](/reference/tokens) for more detail.
Once you have an API token, there are different ways to get your data into Axiom:
* Using the [Ingest API](#ingest-api)
* Using [OpenTelemetry](/send-data/opentelemetry)
* Using a [data shipper](#data-shippers) (Logstash, Filebeat, Metricbeat, Fluentd, etc.)
* Using the [Elasticsearch Bulk API](/send-data/elasticsearch-bulk-api) that Axiom supports natively
* Using [endpoints](#endpoints)
To use dedicated apps that enrich your Axiom organization, go to [Apps](/apps/introduction) instead.
## Ingest method
Select the method to ingest your data. Each ingest method follows a particular path.
### Client libraries
Get [started with apps here](/apps/introduction)
## Endpoints
Endpoints enable you to easily integrate Axiom into your existing data flow by allowing you to use tools and libraries that you are already familiar with.
You can create an endpoint for the following services and send the logs directly to Axiom:
* [Datadog](/send-data/datadog)
* [Honeycomb](/endpoints/honeycomb)
* [Loki](/endpoints/loki)
* Secure Syslog
* [Splunk](/endpoints/splunk)
## Limits and requirements
Axiom applies certain limits and requirements on the ingested data to guarantee good service across the platform. Some of these limits depend on your pricing plan, and some of them are applied system-wide. For more information, see [Limits and requirements](/reference/field-restrictions).
The most important field requirement is about the timestamp.
...
);
}
```
Web Vitals are only sent from production deployments.
## Logs
Send logs to Axiom from different parts of your app. Each log function call takes a message and an optional `fields` object.
```ts
log.debug('Login attempt', { user: 'j_doe', status: 'success' }); // Results in {"message": "Login attempt", "fields": {"user": "j_doe", "status": "success"}}
log.info('Payment completed', { userID: '123', amount: '25USD' });
log.warn('API rate limit exceeded', { endpoint: '/users/1', rateLimitRemaining: 0 });
log.error('System Error', { code: '500', message: 'Internal server error' });
```
### Route handlers
Wrap your route handlers in `withAxiom` to add a logger to your request and log exceptions automatically:
```ts
import { withAxiom, AxiomRequest } from 'next-axiom';
export const GET = withAxiom((req: AxiomRequest) => {
req.log.info('Login function called');
// You can create intermediate loggers
const log = req.log.with({ scope: 'user' });
log.info('User logged in', { userId: 42 });
return NextResponse.json({ hello: 'world' });
});
```
### Client components
To send logs from client components, add `useLogger` from next-axiom to your component:
```ts
'use client';
import { useLogger } from 'next-axiom';
export default function ClientComponent() {
const log = useLogger();
log.debug('User logged in', { userId: 42 });
return Logged in
; } ``` ### Server components To send logs from server components, add `Logger` from next-axiom to your component, and call flush before returning: ```ts import { Logger } from 'next-axiom'; export default async function ServerComponent() { const log = new Logger(); log.info('User logged in', { userId: 42 }); // ... await log.flush(); returnLogged in
; } ``` ### Log levels The log level defines the lowest level of logs sent to Axiom. Choose one of the following levels (from lowest to highest): * `debug` is the default setting. It means that you send all logs to Axiom. * `info` * `warn` * `error` means that you only send the highest-level logs to Axiom. * `off` means that you don’t send any logs to Axiom. For example, to send all logs except for debug logs to Axiom: ```sh export NEXT_PUBLIC_AXIOM_LOG_LEVEL=info ``` ## Capture errors To capture routing errors, use the [error handling mechanism of Next.js](https://nextjs.org/docs/app/building-your-application/routing/error-handling): 1. Go to the `app` folder. 2. Create an `error.tsx` file. 3. Inside your component function, add `useLogger` from next-axiom to send the error to Axiom. For example: ```ts "use client"; import NavTable from "@/components/NavTable"; import { LogLevel } from "@/next-axiom/logger"; import { useLogger } from "next-axiom"; import { usePathname } from "next/navigation"; export default function ErrorPage({ error, }: { error: Error & { digest?: string }; }) { const pathname = usePathname() const log = useLogger({ source: "error.tsx" }); let status = error.message == 'Invalid URL' ? 404 : 500; log.logHttpRequest( LogLevel.error, error.message, { host: window.location.href, path: pathname, statusCode: status, }, { error: error.name, cause: error.cause, stack: error.stack, digest: error.digest, }, ); return (
Ops! An Error has occurred:{" "}
);
}
```
## Extend logger
To extend the logger, use `log.with` to create an intermediate logger. For example:
```typescript
const logger = userLogger().with({ userId: 42 });
logger.info('Hi'); // will ingest { ..., "message": "Hi", "fields" { "userId": 42 }}
```
# Send OpenTelemetry data to Axiom
Learn how OpenTelemetry-compatible events flow into Axiom and explore Axiom comprehensive observability through browsing, querying, dashboards, and alerting of OpenTelemetry data.
OpenTelemetry (OTel) is a set of APIs, libraries, and agents to capture distributed traces and metrics from your app. It’s a Cloud Native Computing Foundation (CNCF) project that was started to create a unified solution for service and app performance monitoring.
The OpenTelemetry project has published strong specifications for the three main pillars of observability: logs, traces, and metrics. These schemas are supported by all tools and services that support interacting with OpenTelemetry. Axiom supports OpenTelemetry natively on an API level, allowing you to connect any existing OpenTelemetry shipper, library, or tool to Axiom for sending data.
OpenTelemetry-compatible events flow into Axiom, where they’re organized into datasets for easy segmentation. Users can create a dataset to receive OpenTelemetry data and obtain an API token for ingestion. Axiom provides comprehensive observability through browsing, querying, dashboards, and alerting of OpenTelemetry data.
OTel traces and OTel logs support are already live. Axiom will soon support OpenTelemetry Metrics (OTel Metrics).
| OpenTelemetry component | Currently supported |
| ------------------------------------------------------------------ | ------------------- |
| [Traces](https://opentelemetry.io/docs/concepts/signals/traces/) | Yes |
| [Logs](https://opentelemetry.io/docs/concepts/signals/logs/) | Yes |
| [Metrics](https://opentelemetry.io/docs/concepts/signals/metrics/) | No (coming soon) |
## OpenTelemetry Collector
Configuring the OpenTelemetry collector is as simple as creating an HTTP exporter that sends data to the Axiom API together with headers to set the dataset and API token:
```yaml
exporters:
otlphttp:
compression: gzip
endpoint: https://api.axiom.co
headers:
authorization: Bearer `{error.message}`
**Settings > Endpoints**.
2. Click **New endpoint**.
3. Click **{endpointName_0}**.
4. Name the endpoint.
5. Select the dataset where you want to send data.
6. Copy the URL displayed for the newly created endpoint. This is the target URL where you send the data.
### Create log stream in Render
In Render, create a log stream. For more information, see the [Render documentation](https://docs.render.com/log-streams). As the log endpoint, use the target URL generated in Axiom in the procedure above.
Back in your Axiom dataset, you see logs coming from Render.
# Send data from Serverless to Axiom
This page explains how to send data from Serverless to Axiom.
Serverless is an open-source web framework for building apps on AWS Lambda. Sending event data from your Serverless apps to Axiom allows you to gain deep insights into your apps’ performance and behavior without complex setup or configuration.
To send data from Serverless to Axiom:
1. [Create an Axiom account](https://app.axiom.co/register).
2. [Create an API token in Axiom](/reference/tokens) with **Ingest**, **Query**, **Datasets**, **Dashboards**, and **Monitors** permissions.
3. [Create a Serverless account](https://app.serverless.com/).
4. Set up your app with Serverless using the [Serverless documentation](https://www.serverless.com/framework/docs/getting-started).
5. Configure Axiom in your Serverless Framework Service using the [Serverless documentation](https://www.serverless.com/framework/docs/guides/observability/axiom).
# Send data from syslog to Axiom
This page explains how to send data from a syslog logging system to Axiom.
The Axiom Syslog Proxy acts as a syslog server to send data to Axiom.
**Settings > Endpoints**.
2. Click **New endpoint**.
3. Click **{endpointName_0}**.
4. Name the endpoint.
5. Select the dataset where you want to send data.
6. Copy the URL displayed for the newly created endpoint. This is the target URL where you send the data.
In the code below, replace `url` with the URL of your Syslog endpoint.
```troy
define flow client_sink_only
flow
use std::time::nanos;
use tremor::pipelines;
define connector input from file
args
file = "in.json" # Default input file is 'in.json' in current working directory
with
codec = "json", # Data is JSON encoded
preprocessors = ["separate"], # Data is newline separated
config = {
"path": args.file,
"mode": "read"
},
end;
create connector input;
define connector syslog_forwarder from tcp_client
args
endpoint_hostport,
with
tls = true,
codec = "syslog",
config = {
"url": "#{args.endpoint_hostport}",
"no_delay": false,
"buf_size": 1024,
},
reconnect = {
"retry": {
"interval_ms": 100,
"growth_rate": 2,
"max_retries": 3,
}
}
end;
create connector syslog_forwarder
with
endpoint_hostport = "tcp+tls://testsyslog.syslog.axiom.co:6514"
end;
create pipeline passthrough from pipelines::passthrough;
connect /connector/input to /pipeline/passthrough;
connect /pipeline/passthrough to /connector/syslog_forwarder;
end;
deploy flow client_sink_only;
```
# Send data from Vector to Axiom
This step-by-step guide will help you configure Vector to read and collect metrics from your sources using the Axiom sink.
Vector is a lightweight and ultra-fast tool for building observability pipelines. It has a built-in support for shipping logs to Axiom through the [`axiom` sink](https://vector.dev/docs/reference/configuration/sinks/axiom/).
## Prerequisites
* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to update the dataset you have created.
## Installation
Follow the [quickstart guide in the Vector documentation](https://vector.dev/docs/setup/quickstart/) to install Vector, and to configure sources and sinks.