|
| 1 | +--- |
| 2 | +id: macro |
| 3 | +title: macro Operator (Beta) |
| 4 | +sidebar_label: macro |
| 5 | +--- |
| 6 | +import useBaseUrl from '@docusaurus/useBaseUrl'; |
| 7 | + |
| 8 | +<head> |
| 9 | + <meta name="robots" content="noindex" /> |
| 10 | +</head> |
| 11 | + |
| 12 | +<p><a href="/docs/beta"><span className="beta">Beta</span></a></p> |
| 13 | + |
| 14 | +The `macro` operator provides a means for you to reference set of query language syntax using a macro keyword across multiple queries. Additionally, if required you can include arguments and performs its respective evaluation of the arguments to this operator. |
| 15 | + |
| 16 | + |
| 17 | +To use the `macro` operator, reference it in your query with backticks (``). Macros can also be nested, enabling complex query reuse: |
| 18 | +* **Nested Macros**. A macro referenced inside another macro. |
| 19 | +* **Inner Macro**. A macro used within the context of another macro query. |
| 20 | +* **Outer Macro**. The macro that references an inner macro. |
| 21 | + |
| 22 | +:::note |
| 23 | +- Only **Administrators** and **Users** with access to **Query Reference** can run queries using macros. |
| 24 | +- Only users with **Administrator** access can create macros. |
| 25 | +::: |
| 26 | + |
| 27 | +## Syntax |
| 28 | + |
| 29 | +``` |
| 30 | +`<macro name>` |
| 31 | +``` |
| 32 | + |
| 33 | +## Add a macro |
| 34 | + |
| 35 | +To create a macro, follow the steps below: |
| 36 | + |
| 37 | +1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic). In the main Sumo Logic menu, select **Manage Data** > **Logs** > **Macros**. <br/> [**New UI**](/docs/get-started/sumo-logic-ui/). In the top menu, select **Manage Date**, and then under **Logs**, select **Macros**. You can also click the **Go To...** menu at the top of the screen and select **Macros**. |
| 38 | +1. Click **+ Add Macro **.< br/><img src={useBaseUrl('img/search/searchquerylanguage/search-operators/macro-logs-page.png')} alt="macro-logs-page" style={{border: '1px solid gray'}} width="800" /> |
| 39 | +1. Or, in the log search page, select the part of search query language that needs to be reused and click on **Create Macro **.< br/><img src={useBaseUrl('img/search/searchquerylanguage/search-operators/macro-search-page.png')} alt="macro-search-page" style={{border: '1px solid gray'}} width="800" /> |
| 40 | +1. **Macro Details**. Enter the name for the macro. Description is optional. |
| 41 | +1. **Macro Definition**. Enter the definition for the macro. To add arguments use the `{{Arg}}` syntax or select a part of the definition and click on **Add Argument**. |
| 42 | +1. (Optional) **Arguments**. Enter the name and select the data type for the argument selected. |
| 43 | +1. (Optional) **Argument Validation**. Define the validation condition and enter the error message that needs to be shown when the validation expression returns false. |
| 44 | +1. **Usage**. Preview of how you use the macro in the log search. |
| 45 | +1. Click **Submit** to save the macro. |
| 46 | + |
| 47 | +### Limitations |
| 48 | + |
| 49 | +- You can create a maximum of 50 macros. |
| 50 | +- You can add a maximum of 5 arguments. |
| 51 | +- You cannot edit or delete the macro. Submit a customer request to Sumo Logic if you still need to edit or delete a macro. |
| 52 | + |
| 53 | +### Example without arguments |
| 54 | + |
| 55 | +Consider the below query, which searches for errors with `timeslice` of 5 minutes. |
| 56 | + |
| 57 | +``` |
| 58 | +_sourceCategory=error | timeslice 5m |
| 59 | +| count by _timeslice |
| 60 | +``` |
| 61 | + |
| 62 | +Now, by creating a macro for the `timeslice` field, the query using the macro operator can be simplified as follows: |
| 63 | + |
| 64 | +``` |
| 65 | +_sourceCategory=error | `timeslice_macro` |
| 66 | +``` |
| 67 | + |
| 68 | +### Example with arguments |
| 69 | + |
| 70 | +Consider the below query, which searches for errors with `timeslice` for time of your choice. |
| 71 | + |
| 72 | +``` |
| 73 | +_sourceCategory=error | timeslice 5m |
| 74 | +| count by _timeslice |
| 75 | +``` |
| 76 | + |
| 77 | +To create a macro that allows you to enter a value of your choice, we use arguments during the macro creation process. You may choose to include validation conditions within these arguments. If validation conditions are present, make sure to specify the correct data type for `<arg1_value>` to achieve the desired results. |
| 78 | + |
| 79 | +The following is a simplified version of the query that uses the macro operator with arguments. Replace `<arg1_value>` with the value of your choice. |
| 80 | + |
| 81 | +``` |
| 82 | +_sourceCategory=error | `timeslice_macro(<arg1_value>)` |
| 83 | +``` |
| 84 | + |
| 85 | +## View and use the macro operator |
| 86 | + |
| 87 | +To view any existing macro, follow the steps below: |
| 88 | + |
| 89 | +1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic). In the main Sumo Logic menu, select **Manage Data** > **Logs** > **Macros**. <br/> [**New UI**](/docs/get-started/sumo-logic-ui/). In the top menu, select **Manage Date**, and then under **Logs**, select **Macros**. You can also click the **Go To...** menu at the top of the screen and select **Macros**. |
| 90 | +1. In the **Macros ** page, click on any of the macros that you want to view the macro details.< br/><img src={useBaseUrl('img/search/searchquerylanguage/search-operators/view-macro-logs-page.png')} alt="macro-logs-page" style={{border: '1px solid gray'}} width="800" /> |
| 91 | +1. To use the selected macro in your log search query, copy the suggested **Usage ** of the macro and include it in your query syntax. < br/><img src={useBaseUrl('img/search/searchquerylanguage/search-operators/view-macro-logs-details.png')} alt="view-macro-logs-details" style={{border: '1px solid gray'}} width="400" /> |
0 commit comments