Accessing search logs of asset

Search logs provide valuable insights for analysts to monitor the popularity of assets within Atlan, including details such as the most visited assets, user interactions, and emerging search patterns. Accessing the search log of an asset is a flexible operation, which may seem more intricate compared to other operations. To harness the complete flexibility of Atlan's search, the SDK introduces a dedicated SearchLogRequest object.

Similar but not identical to searching in general

Atlan's search log, which contains the search logs of an asset, utilizes Elasticsearch. This makes the approach to accessing search logs similar to searching. However, there are differences, as the search log uses a distinct index from the broader search. If you're feeling adventurous, feel free to experiment with the more complex search mechanisms outlined in the searching section. Nevertheless, this should be sufficient to help you get started with accessing asset search logs.

Most recent viewers of asset

To retrieve the most recent viewers of an asset:

Java

Retrieve the most recent viewers of an asset

List<UserViews> viewers = SearchLog.mostRecentViewers( // (1)
    client, "955c455d-cfea-4c9c-844d-e226edf8b6da", 20, List.of("atlansupport")
);

for (UserViews viewer: viewers)

1. You must provide GUID of the asset and specify the maximum number of recent users to be considered for the search log request.

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

   Because this operation will directly look up the asset's views in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

2. You can then iterate through each recent viewers.

3. Name of the user who viewed the asset.

4. Number of times the user viewed the asset.

5. When the user most recently viewed the asset (epoch-style), in milliseconds.

Python

Retrieve the most recent viewers of an asset

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.search_log import SearchLogRequest

client = AtlanClient()

request = SearchLogRequest.most_recent_viewers(  # (1)
    guid="955c455d-cfea-4c9c-844d-e226edf8b6da",
    max_users=20,
    exclude_users=["atlansupport"],
)
response = client.search_log.search(request)

for viewer in response.user_views: # (2)
    user = viewer.username # (3)
    view_count = viewer.view_count # (4)
    last_accessed = viewer.most_recent_view # (5)

1. You must provide a GUID and specify the maximum number of recent users to be considered for the search log request.
   • Optionally, you may provide a list of usernames to be excluded from the search log results.
2. You can then iterate through each recent viewers.
3. Name of the user who viewed the asset.
4. Number of times the user viewed the asset.
5. When the user most recently viewed the asset (epoch-style), in milliseconds.

Kotlin

Retrieve the most recent viewers of an asset

val viewers = SearchLog.mostRecentViewers( // (1)
    client, "955c455d-cfea-4c9c-844d-e226edf8b6da", maxUsers=20, listOf("atlansupport")
)

for (viewer in viewers)

1. You must provide a GUID and specify the maximum number of recent users to be considered for the search log request.

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

Because this operation will directly look up the asset's views in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

2. You can then iterate through each recent viewers.
3. Name of the user who viewed the asset.
4. Number of times the user viewed the asset.
5. When the user most recently viewed the asset (epoch-style), in milliseconds.

Raw REST API

POST /api/meta/search/searchlog

{
   "dsl": {
     "from": 0,
     "size": 0,
     "aggregations": {
       "uniqueUsers": {
         "aggregations": {
           "latestTimestamp": {
             "max": {
               "field": "timestamp"
             }
           }
         },
         "terms": {
           "field": "userName",
           "order": [
             {
               "latestTimestamp": "desc"
             }
           ],
           "size": 20 // (2)
         }
       },
       "totalDistinctUsers": {
         "cardinality": {
           "field": "userName",
           "precision_threshold": 1000
         }
       }
     },
     "query": {
       "bool": {
        "must_not": [
          {
            "terms": {
              "userName": [
                "atlansupport"
              ] // (3)
            }
          }
        ],
         "filter": [
           {
             "term": {
               "utmTags": {
                 "value": "action_asset_viewed"
               }
             }
           },
           {
             "term": {
               "entityGuidsAll": {
                 "value": "955c455d-cfea-4c9c-844d-e226edf8b6da", // (1)
                 "case_insensitive": false
               }
             }
           },
           {
             "bool": {
               "minimum_should_match": 1,
               "should": [
                 {
                   "term": {
                     "utmTags": {
                       "value": "ui_profile"
                     }
                   }
                 },
                 {
                   "term": {
                     "utmTags": {
                       "value": "ui_sidebar"
                     }
                   }
                 }
               ]
             }
           }
         ]
       }
     },
     "sort": [
       {
         "timestamp": {
           "order": "asc"
         }
       }
     ],
     "track_total_hits": true
   }
}

1. GUID of the asset for which you are seeking the details of recent viewers.
2. Maximum number of recent users to be considered for the search log request.
3. Optionally, you may provide a list of usernames to be excluded from the search log results.

Most viewed assets

To retrieve the most viewed assets by its total views:

Java

Retrieve the most viewed assets by its total views

List<AssetViews> topAssetsByViews = SearchLog.mostViewedAssets(
  client, 10, false, List.of("atlansupport") // (1)
);

for (AssetViews detail: topAssetsByViews)

1. To retrieve the most viewed assets, specify the maximum number of assets you want to retrieve. Then specify whether you want the most-viewed based on total number of views, irrespective of distinct users (false); or based on the most distinct users, irrespective of total views (true).

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

Because this operation will directly look up the asset's views in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

2. You can then iterate through each asset's views.
3. GUID of the asset that was viewed.
4. Number of times the asset has been viewed (in total).
5. Number of distinct users that have viewed the asset.

Python

Retrieve the most viewed assets by its total view

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.search_log import SearchLogRequest

client = AtlanClient()

request = SearchLogRequest.most_viewed_assets(  # (1)
    max_assets=10,
    by_different_user=False,
    exclude_users=["username"],
)
response = client.search_log.search(request)

for detail in response.asset_views: # (2)
    guid = detail.guid # (3)
    total_views = detail.total_views # (4)
    distinct_users = detail.distinct_users # (5)

1. To retrieve the most viewed assets, specify the maximum number of assets you want to retrieve. Then specify whether you want the most-viewed based on total number of views, irrespective of distinct users (False); or based on the most distinct users, irrespective of total views (True).
   • Optionally, you may provide a list of usernames to be excluded from the search log results.
2. You can then iterate through each asset's viewers.
3. Name of the user who viewed the asset.
4. Number of times the user viewed the asset.
5. Number of distinct users that have viewed the asset.

Kotlin

Retrieve the most viewed assets by its total view

val topAssetsByViews = SearchLog.mostViewedAssets(
    10, byDifferentUsers=false, excludeUsers=listOf("atlansupport")
) // (1)

for (detail in topAssetsByViews)

1. To retrieve the most viewed assets, specify the maximum number of assets you want to retrieve. Then specify whether you want the most-viewed based on total number of views, irrespective of distinct users (false); or based on the most distinct users, irrespective of total views (true).

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

Because this operation will directly look up the asset's views in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

2. You can then iterate through each asset's viewers.
3. Name of the user who viewed the asset.
4. Number of times the user viewed the asset.
5. Number of distinct users that have viewed the asset.

Raw REST API

POST /api/meta/search/searchlog

{
 "dsl": {
   "from": 0,
   "size": 0,
   "aggregations": {
     "uniqueAssets": {
       "aggregations": {
         "uniqueUsers": {
           "cardinality": {
             "field": "userName",
             "precision_threshold": 1000
           }
         }
       },
       "terms": {
         "field": "entityGuidsAll",
         "size": 10 // (1)
         // (2)
       }
     },
     "totalDistinctUsers": {
       "cardinality": {
         "field": "userName",
         "precision_threshold": 1000
       }
     }
   },
   "query": {
     "bool": {
       "must_not": [
         {
           "terms": {
             "userName": [
               "atlansupport"
             ] // (3)
           }
         }
       ],
       "filter": [
         {
           "term": {
             "utmTags": {
               "value": "action_asset_viewed"
             }
           }
         },
         {
           "bool": {
             "minimum_should_match": 1,
             "should": [
               {
                 "term": {
                   "utmTags": {
                     "value": "ui_profile"
                   }
                 }
               },
               {
                 "term": {
                   "utmTags": {
                     "value": "ui_sidebar"
                   }
                 }
               }
             ]
           }
         }
       ]
     }
   },
   "sort": [
     {
       "timestamp": {
         "order": "asc"
       }
     }
   ],
   "track_total_hits": true
 }
}

1. Maximum number of assets to be considered for the search log request
2. If you want to retrieve most viewed assets based on the most distinct users, regardless of total views, include "order": [{"uniqueUsers": "desc"}] here.
3. Optionally, you may provide a list of usernames to be excluded from the search log results.

Detailed search log entries

To retrieve detailed search log entries (paged via lazy fetching):

Java

To retrieve detailed search log entries

SearchLog.viewsByGuid(
        client,
        "955c455d-cfea-4c9c-844d-e226edf8b6da",
        List.of("atlansupport")
    ) // (1)
    .stream() // (2)
    .limit(100) // (3)
    .forEach(entry -> { // (4)
        logger.info(entry.getUserName() + " from " + entry.getIpAddress());
    });

1. You must provide the GUID of the asset for which you are seeking the detailed search log entries.

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

   Because this operation will directly look up the asset's views in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

2. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream

3. With streaming, you can apply your own limits to the maximum number of results you want to process.

   Independent of page size

Note that this is independent of page size. You could page through results 50 at a time, but only process a maximum of 100 total results this way. Since the results are lazily-loaded when streaming, only the first two pages of results would be retrieved in such a scenario. ::: 4. You can then iterate through each log entry to retrieve details such as the username and IP address of the search logs.

Python

To retrieve detailed search log entries

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.search_log import SearchLogRequest

client = AtlanClient()

request = SearchLogRequest.views_by_guid(  # (1)
    guid="955c455d-cfea-4c9c-844d-e226edf8b6da",
    size=20,
    exclude_users=["atlansupport"],
)

response = client.search_log.search(criteria=request, bulk=False) # (2)

for entry in response: # (3)
    LOGGER.info(f"{entry.user_name} from {entry.ip_address}")

1. You must provide the GUID of the asset and specify the maximum number of log entries per page for the search log request.

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

2. client.search_log.search() method takes following parameters:

   • criteria: defines the search query to execute the search.
   • bulk(default: False): specifies whether to execute the search in bulk mode for retrieving the search logs matching the criteria. This mode is optimized for handling large results (more than 10,000). When enabled (True), the results will be reordered based on the creation timestamp to facilitate iterating through large datasets.
   note

If the number of results exceeds the predefined threshold (10,000 assets) search log search will be automatically converted into a bulk search. ::: 3. You can then iterate through each log entry to retrieve details such as the username and IP address of the search logs.

Kotlin

To retrieve detailed search log entries

  SearchLog.viewsByGuid(
        client,
        "955c455d-cfea-4c9c-844d-e226edf8b6da",
        listOf("atlansupport")
    ) // (1)
    .stream() // (2)
    .limit(100) // (3)
    .forEach { entry -> // (4)
        logger.info { "${entry.userName} from ${entry.ipAddress}" }
    }

1. You must provide the GUID of the asset for which you are seeking the detailed search log entries.

   • Optionally, you may provide a list of usernames to be excluded from the search log results.

   Because this operation will directly look up the asset's views in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

2. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream

3. With streaming, you can apply your own limits to the maximum number of results you want to process.

   Independent of page size

Note that this is independent of page size. You could page through results 50 at a time, but only process a maximum of 100 total results this way. Since the results are lazily-loaded when streaming, only the first two pages of results would be retrieved in such a scenario. ::: 4. You can then iterate through each log entry to retrieve details such as the username and IP address of the search logs.

Raw REST API

POST /api/meta/search/searchlog

{
    "dsl": {
      "from": 0,
      "size": 100, // (1)
      "query": {
        "bool": {
          "must_not": [
            {
              "terms": {
                "userName": [
                  "atlansupport"
                ] // (3)
              }
            }
          ],
          "filter": [
            {
              "term": {
                "utmTags": {
                  "value": "action_asset_viewed"
                }
              }
            },
            {
              "term": {
                "entityGuidsAll": {
                  "value": "955c455d-cfea-4c9c-844d-e226edf8b6da", // (2)
                  "case_insensitive": false
                }
              }
            },
            {
              "bool": {
                "minimum_should_match": 1,
                "should": [
                  {
                    "term": {
                      "utmTags": {
                        "value": "ui_profile"
                      }
                    }
                  },
                  {
                    "term": {
                      "utmTags": {
                        "value": "ui_sidebar"
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "sort": [
        {
          "timestamp": {
            "order": "asc"
          }
        }
      ],
      "track_total_hits": true
    }
}

1. Page size of the search log request.
2. GUID of the asset for which you are seeking the detailed search log entries.
3. Optionally, you may provide a list of usernames to be excluded from the search log results.