收集遥测数据以用于分析搜索流量

项目
12/20/2024

搜索流量分析是一种模式，用于收集有关用户与 Azure AI 搜索应用程序之间的交互（例如用户发起的点击流事件和键盘输入）的遥测数据。使用此信息可以确定搜索解决方案的有效性，包括点击率以及哪些查询输入产生了零个结果。

检测包括以下组成部分：

添加遥测客户端
修改搜索请求，使其包含将搜索结果映射到用户操作的关联 ID
创建自定义事件并将其发送到 Application Insights，同时使用可视化和报告工具查看事件数据

此模式依赖于 Application Insights（Azure Monitor 的一项功能）来收集用户数据。需要按照本文所述在应用程序代码中添加检测。最后，需要使用报告机制分析数据。可以使用连接到 Application Insights 的任何可视化工具。

注意

本文中所述的模式适用于你添加到客户端的代码生成的高级方案和点击流数据。相比之下，服务日志易于设置，提供各种指标（包括搜索词），无需编写任何代码即可在门户中操作。建议为所有方案启用日志记录。有关详细信息，请参阅收集和分析日志数据。

先决条件

Azure AI 搜索，任何区域，基本层及更高级别层。
Application Insights。
提供交互式搜索体验的富客户端应用程序，其中包括点击流事件或其他要关联到搜索结果选择的用户操作。

标识相关的搜索数据

若要为搜索流量分析收集有用的指标，必须从搜索应用程序的用户记录一些信号。这些信号表示用户感兴趣的内容以及他们认为相关的内容。对于搜索流量分析，这些信号包括：

用户生成的搜索事件：只有用户发起的搜索查询才是需要关注的。其他搜索请求（例如用于填充方面或检索内部信息的搜索请求）并不重要。请确保只检测用户启动的事件，以避免结果中出现扭曲或偏差。
用户生成的点击流事件：在搜索结果页上，点击流事件通常意味着某个文档是特定搜索查询的相关结果。

在应用程序代码中，应将这些事件与给定查询返回的搜索结果相关联。将搜索和点击流事件链接到相关 ID，可以更深入地了解应用程序搜索功能的表现。

添加搜索流量分析

对于 Azure AI 搜索，Azure 门户提供了一个搜索流量分析页，其中包含用于添加遥测客户端、请求标头和自定义日志事件所需属性的 C# 和 JavaScript 代码片段。

重要

搜索流量分析门户页当前已过期并引用了过时的客户端库。解决方法是使用 azure-search-traffic-analytics GitHub 存储库中的代码片段。本文包含 GitHub 存储库中的代码片段。

步骤 1：设置 Application Insights

创建一个用于将事件发送到 Application Insights 的对象。可以将检测机制添加到服务器端应用程序代码中或在浏览器中运行的客户端代码中，此处的代码以 C# 和 JavaScript 变体表示。有关其他语言，请参阅受支持的平台和框架。

服务器端遥测将捕获应用程序层（例如，在 Azure 上作为 Web 服务运行的应用程序，或者在企业网络中作为本地应用运行的应用程序）的指标。服务器端遥测捕获搜索和点击流事件、文档在结果中的位置以及查询信息，但数据收集范围将限定为该层上提供的任何信息。

在客户端上，可以使用附加的代码来操作查询输入、添加导航或包含上下文（例如，从主页或产品页发起的查询）。如果这种描述符合你的解决方案，可以选择启用客户端检测，使遥测数据反映额外的详细信息。如何收集这些额外的详细信息超出了此模式的范围，但你可以查看适用于网页的 Application Insights以获取有关该决定的帮助。

在此步骤中，提供 Application Insights 的连接字符串。

以下步骤反映了适用于某些 Visual Studio 项目类型的快捷方式。

在 Visual Studio 中打开解决方案。
在“项目”菜单上，选择“连接服务”“添加”“Azure Application Insights”>>。
在“连接到依赖项”中，依次选择“Azure Application Insights”、“下一步”。
依次选择 Azure 订阅、Application Insights 资源、“完成”。

此时，已经为应用程序监视设置了应用程序，这意味着，会使用默认指标跟踪客户端应用中的所有页面加载。

如果此快捷方式不起作用，请参阅启用 Application Insights 服务器端遥测或参考相邻选项卡中的代码片段。

var telemetryConfiguration = new TelemetryConfiguration
{
    ConnectionString = "<PUT YOUR CONNECTION STRING HERE>"
};
var telemetryClient = new TelemetryClient(telemetryConfiguration);

const appInsights = new ApplicationInsights({ config: {
  connectionString: '<PUT YOUR CONNECTION STRING HERE>'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();

步骤 2：添加检测

将检测代码添加到客户端应用程序。

将点击流事件与搜索结果相关联

为了将搜索请求与单击相关联，必须具有一个将这两个不同事件关联起来的相关性 ID。使用 HTTP 标头请求搜索 ID 时，Azure AI 搜索将提供该 ID。

使用搜索 ID 可将 Azure AI 搜索为请求本身发出的指标关联到在 Application Insights 中记录的自定义指标。

.NET
JavaScript

var client = new SearchClient(new Uri("https://contoso.search.azure.cn"), "hotels-sample-index", new DefaultAzureCredential());

// Generate a new correlation id for logs
string searchId = Guid.NewGuid().ToString();
string searchText = "*";
SearchResults<SearchDocument> searchResults;

// Set correlation id for search request
using (HttpPipeline.CreateClientRequestIdScope(clientRequestId: searchId))
{
    searchResults = client.Search<SearchDocument>(searchText, options: new SearchOptions { IncludeTotalCount = true } );
}

const searchId = uuidv4();
const searchText = "*";
const searchResults = await searchClient.search(searchText, { includeTotalCount: true, customHeaders: { "x-ms-client-request-id": searchId }});
const properties = {
    searchId: searchId,
    serviceName: "<PUT YOUR SEARCH SERVICE NAME HERE, example contoso-search>",
    indexName: "<PUT YOUR INDEX NAME HERE>",
    searchText: searchText,
    resultsCount: searchResults.count
};
appInsights.trackEvent({ name: "search" }, properties);

记录自定义事件

每当用户发出搜索请求时，应使用 Application Insights 自定义事件上的以下架构将该请求作为搜索事件进行记录。请记得仅记录用户生成的搜索查询。

SearchId：(GUID) 搜索查询的唯一标识符（内置到搜索响应中）
SearchServiceName：（字符串）搜索服务名称
IndexName：（字符串）要查询的搜索服务索引
SearchText：（字符串）用户输入的搜索词
ResultCount：（整数）返回的文档数（内置到搜索响应中）

注意

通过向搜索查询添加 $count=true 来请求用户生成的查询的计数。有关详细信息，请参阅搜索文档 (REST)。

.NET
JavaScript

// Create properties for telemetry
var properties = new Dictionary<string, string>
{
    ["searchId"] = searchId,
    ["serviceName"] = "<PUT YOUR SEARCH SERVICE NAME HERE, example: contoso-search>",
    ["indexName"] = "<PUT YOUR INDEX NAME HERE>",
    ["searchText"] = searchText,
    ["resultsCount"] = searchResults.TotalCount?.ToString()
};

const properties = {
    searchId: searchId,
    serviceName: "<PUT YOUR SEARCH SERVICE NAME HERE, example contoso-search>",
    indexName: "<PUT YOUR INDEX NAME HERE>",
    searchText: searchText,
    resultsCount: searchResults.count
};

将自定义事件发送到 Application Insights

将自定义事件添加到 Application Insights 的自定义事件表中。有关更多信息，请参阅用于处理自定义事件和指标的 Application Insights API。

.NET
JavaScript

telemetryClient.TrackEvent("search", properties);
telemetryClient.Flush();

appInsights.trackEvent({ name: "search" }, properties);

步骤 3：审阅日志

使用 Application Insights 支持的任何方法来查看自定义事件。

后续步骤

你可以查找有关 Application Insights 的更多信息并访问定价页面来详细了解其各种服务层级。

详细了解如何创建报表。有关详细信息，请参阅 Power BI Desktop 入门。

通过