Often, the logs would not contain all the required information to consolidate the analysis. In such cases, you can create a lookup table to pickup the information that you have already collated to make more sense of the data in the logs. For example, the Error ID field in log events doesn’t provide a description of the errors. You can create a lookup that maps Error ID to descriptions, and then use the Field Enrichment options to make the descriptions available to search in the log records. Some example scenarios where you could create lookups:

• Product inventory: Product ID, technical specifications, price, available stock, rack number
• Employee information: Employee ID, Personal information, organization, role, scale, salary, manager
• Library reference: Tile, author, summary, edition, previous editions, price

You can primarily use the simple lookups at ingest-time using the Source Lookup function. See Use Ingest-Time Lookups in the Source.

You can also use simple lookups at query-time as shown below:

In the following lookup query, the error message is picked up from the lookup table ORA Error Messages by mapping the Error ID field, and displayed in a summary table along with other fields like log source and entity:

'Error ID' like 'ORA%' | lookup table = 'ORA Error Messages' select errmsg using 'Error ID' = errid | fields -*, 'Log Source', Entity, errmg

• Information from the logs:
  • Error ID: Error ID as mentioned in the logs specified in the form ORA%
  • Log Source: The log source of the logs
  • Entity: The entity of the logs
• Information from the Oracle-defined lookup table ORA Error Messages:
  • errid: The error ID specified in the form ORA%
  • errmsg: The error message for the error ID

  The other details available in the ORA Error Messages lookup table are errcause (Error Cause) and erraction (Error Action) for each error ID. To view the contents of the lookup table, use the searchlookup command as follows:

  * | searchlookup table = 'ORA Error Messages'

1. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Administration. The Administration Overview page opens.

2. The administration resources are listed in the left hand navigation pane under Resources. Click Lookups.

3. Under Lookups, click on the lookup whose details you want to view.

   The Lookup Detail page displays the details that you had provided while creating it, and also the content of the lookup table. You can also perform the actions like Move resource, Add tags, and Delete. For details about these actions, see the following section.

To perform other actions on the lookup, in the Lookups listing page, select the Compartment, Type, and Creation Type of your lookup, and narrow down your search for your lookup in the Filters section. You can also include Tag filters to filter lookups by tags. After identifying your lookup, click Actions icon in the row of your lookup:

• Reupload File: In case of user-created lookups, if you have a new version of the lookup table, or if a previous upload has failed, then you can re-upload it.

• Delete: You may have to delete some of your old or unused lookups. To delete the lookup, confirm in the Delete Lookup dialog box. You can delete a lookup only if it is user-created.

• Copy OCID: The OCID of the lookup resource is copied. You can use it to refer to this resource anywhere in Oracle Cloud Infrastructure.
• Move resource: The Move Resource to a Different Compartment dialog box is displayed. From the options, select the compartment to which you want to move the lookup, and click Move Resource.
• Add tags: See Add Tags to Logging Analytics Resources.

1. Update your CSV file with the field-value combinations.

2. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Administration. The Administration Overview page opens.

3. The administration resources are listed in the left hand navigation pane under Resources. Click Lookups.

4. Under Lookups, click the Actions icon in the row that corresponds to the lookup that you want to update, click Reupload File.

   The Reupload File dialog box opens.

5. Select the updated lookup CSV file that you had created earlier, and click Upload.

After creating the simple lookup, run a query with the searchlookup command to list the values in the lookup, and use the lookup command in a query to map the output fields to those values.

1. Create a lookup CSV file with the field-value combinations. For example, to create a lookup that maps Error ID to descriptions:

   errid,description
   02323,Network Not Reachable
   09912,User Activity
   12322,Out of Memory

   Note that the first row is the header with errid and description titles for the values in the subsequent rows.

2. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Administration. The Administration Overview page opens.

3. The administration resources are listed in the left hand navigation pane under Resources. Click Lookups.

   The lookups listing page is displayed. From the left hand navigation pane, select the compartment where the lookup must be created.

4. Under Lookups, click Create Lookup.

5. In the Create Lookup page, enter the name of the lookup, such as server error code lookups and an optional description.

6. Under Type, select Simple.

7. Select the lookup CSV file that you had created earlier.

8. Optionally, expand the section Show Advanced Options, and add tags to the lookup. Click Create.

After creating the Dictionary type lookup, use searchlookup command to list the lookups. Use the lookup command to map to the fields with any query only after using the link or cluster commands in the query.

Operator,Condition,Network Name
CIDRMATCH,192.0.2.10/24,Database Network

Operator,Condition,Label,Module
# ----------------------------------
# Startup/Shutdown and Terminations
# ----------------------------------
CONTAINS,Server started in RUNNING mode,Server Started,WebLogic Server
CONTAINS,A critical service failed. The server will shut itself down,Server Shutdown,WebLogic Server
CONTAINS,state changed to FAILED,Server Failed,
CONTAINS,Removing .* from cluster view due to PeerGone,Cluster Removed,WebLogic Server
# ----------------------
# Connection Error / Timeouts and Slowness
# ----------------------
CONTAINS,Unable to connect to WSM policy manager,WSM Policy Manager Connection Error,
CONTAINS REGEX,java.sql.SQLTimeoutException: \S+: user requested cancel of current operation,SQL Timeout,Database
CONTAINS,This member is running extremely slowly and may endanger the rest of the cluster,WebLogic Cluster Slowness,WebLogic Server

You can use the same dictionary in multiple queries. For example, the following query applies the same dictionary to the Message field and shows the rolled up results using the Pie Chart visualization:

'Log Source' = 'Linux Syslog Logs'
| lookup table = 'Linux Error Categories' select Issue, Area using Message
| stats count by Area

Individual resource-type: loganalytics-lookup

Part of aggregate resource-type: loganalytics-features-family

Resource Policy Statement if Family Policy Not Defined:

Note that for the above policy statement to restrict the permission to the lookup resource with the required scope (tenancy or compartment) to work, there mustn't be any other policy statements that cover the resource-type family and a larger scope.

The following operations can be performed with each verb when you create IAM policy for loganalytics-lookup:

Typically, only administrators have USE and MANAGE permissions to create or delete lookup. If you want privileges to run lookup queries, then you require READ permission.

Aggregate Family Policy Statement Which Covers the Permission for the Lookup Resource:

Typically, only administrators have USE and MANAGE permissions to create or delete lookup. If you want privileges to run lookup queries, then you require READ permission.

If you're already using Log Explorer, SDKs, or CLI to run the queries, then you already have the required permissions to run searchlookup or lookup query commands on the existing Oracle-defined and user-created lookups.

If you're using instance principal to run the queries, then provide the following permission if you have not already provided loganalytics-features-family access to the dynamic group:

Allow dynamic-group <dynamic-group-name> to {LOG_ANALYTICS_LOOKUP_READ} in tenancy

OR

Allow dynamic-group <dynamic-group-name> to {LOG_ANALYTICS_LOOKUP_READ} in compartment <compartment_name>