Accessing the search logs of an 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 an asset

2.0.4 4.0.0

To retrieve the most recent viewers of an asset:

Java Python Kotlin Raw REST API

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

for (UserViews viewer: viewers) { // (2)
    String user = viewer.getUsername() // (3)
    Long viewCount = viewer.getViewCount() // (4)
    Long lastAccessed = viewer.getMostRecentView() // (5)
}

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.

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.

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

for (viewer in viewers) { // (2)
     val user = viewer.username  // (3)
     val viewCount = viewer.viewCount // (4)
     val lastAccessed = viewer.mostRecentView // (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.

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.

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

{
   "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

2.0.4 4.0.0

To retrieve the most viewed assets by its total views:

Java Python Kotlin Raw REST API

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

for (AssetViews detail: topAssetsByViews) { // (2)
    String guid = detail.getGuid() // (3)
    Long totalViews = detail.getTotalViews() // (4)
    Long distinctUsers = detail.getDistinctUsers() // (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.

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.

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

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.

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

for (detail in topAssetsByViews) { // (2)
     val guid = detail.username  // (3)
     val totalViews = detail.viewCount // (4)
     val distinctUsers = detail.mostRecentView // (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.

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.

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

{
 "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

2.0.4 4.0.0

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

Java Python Kotlin Raw REST API

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.

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(request)

for entry in response: # (2)
    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. You can then iterate through each log entry to retrieve details such as the username and IP address of the search logs.

  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.

{
    "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.

---