# 在 LOG\_ONLY 模式下测试策略 使用策略级别的强制模式，您可以在`ACTIVE`和之间切换`LOG_ONLY`以回答以下问题：“如果应用此策略，它会对我的流量产生什么影响？” 每策略`LOG_ONLY`模式允许您在不影响授权决策的情况下根据实际流量测试策略。该策略会像强制执行一样评估每个请求，但仅将结果写入日志。实施模式为的策略不会导致任何内容被阻止或允许`LOG_ONLY`。一旦你相信结果，就把它推广到`ACTIVE`。 **Topics** + [“仅限记录” 模式的工作原理](#how-log-only-mode-works) + [仅记录策略和仅限日志策略引擎](#log-only-policies-and-log-only-policy-engines) + [设置策略的执行模式](#set-the-enforcement-mode-of-a-policy) + [观察 LOG\_ONLY 结果](#observe-log-only-results) + [将政策推向执法](#promote-a-policy-to-enforcement) + [在 LOG\_ONLY 模式下选择阈值](#choosing-a-threshold-with-log-only-mode) + [注意事项和限制](#policy-log-only-considerations-and-limitations) ## “仅限记录” 模式的工作原理 策略引擎中的每个策略的强制模式均为`ACTIVE`或`LOG_ONLY`。默认设置为`ACTIVE`，因此现有策略以及您在未指定字段的情况下创建的任何新策略都将像以前一样继续执行。当策略引擎评估请求时，它会并排评估您的`ACTIVE`策略和您的`LOG_ONLY`政策，但仅对您的策略强制执行。`ACTIVE` `ACTIVE`策略决定返回 AgentCore 网关并强制执行的决定。策略引擎应用 “default-deny” 和 “forbid-wins” 语义，这意味着只有在策略允许的情况下才允许请求，而任何活动策略的单个禁令都会拒绝该请求。 `LOG_ONLY`策略是根据同一个请求进行评估的，但其结果是分开的。它们以跟踪形式报告并作为 Amazon CloudWatch 指标发布。它们永远不会合并到强制执行的决定中。 | 执法模式 | 对每个请求进行了评估？ | 影响返回的决定？ | | --- | --- | --- | | `ACTIVE`（默认值） | 支持 | 是 | | `LOG_ONLY` | 是 | 否 | 对请求的评估分为两个阶段： 1. 策略引擎计算决策。只有`ACTIVE`政策才会促成这种情况。 `LOG_ONLY`政策是分开评估和报告的，但从不考虑在内。 1. 如果引擎与处于`ENFORCE`模式的网关关联，则网关会根据策略引擎的决定允许或拒绝该操作。如果引擎与处于`LOG_ONLY`模式的网关关联，则网关不采取任何行动；决策会被记录下来，但不会强制执行。 `ACTIVE`并`LOG_ONLY`被视为两个孤立的集合；`LOG_ONLY`保单永远无法改变来电者的体验。请求收到的决定不受任何`LOG_ONLY`政策的影响。 除了记录与请求匹配的`LOG_ONLY`策略外，策略引擎还会报告其中哪些策略如果是，则会更改决策`ACTIVE`。这是评估政策的有效性和安全性（即是否可以推广到该政策`ACTIVE`）时使用的关键信号。例如，如果`LOG_ONLY`策略频繁匹配并出现在决策翻转集中，则会在观察窗口期间屏蔽您的流量。每项`LOG_ONLY`策略都独立于所有其他`LOG_ONLY`策略进行评估，以确定决策转变策略集。但是，每项`LOG_ONLY`政策评估都考虑了所有现行`ACTIVE`政策。 ## 仅记录策略和仅限日志策略引擎 中的策略 AgentCore 有两个单独的控件，它们都使用值 LOG\_ONLY。它们在不同的层面运作，回答不同的问题，因此了解你在设置哪个层面很重要。 **策略引擎实施模式：**控制引擎的整体行为。如果设置为`LOG_ONLY`，则无论引擎的单个策略模式如何，都不会在引擎中强制执行任何策略。所有决策都会被记录下来。使用`CreateGateway`或`UpdateGateway`操作将策略引擎与网关关联`policyEngineConfiguration`时，使用`mode`字段进行设置。`mode`接受的两个值是`ENFORCE`（默认）和`LOG_ONLY`。 策略模式控制强制引擎中单个策略的行为。当设置为 LOG\_ONLY 时，仍会对该策略进行评估，但其决策会被记录下来，而不是强制执行。引擎中的所有其他`ACTIVE`策略继续正常执行。`enforcementMode`接受的两个值是`ACTIVE`（默认）和`LOG_ONLY`。 使用策略级别 LOG\_ONLY 在生产环境中对新的护栏进行影子测试，而不会影响流量。在启用强制之前，使用引擎级 LOG\_ONLY 来观察所有策略的行为。
策略实施模式
ACTIVE LOG_ONLY
策略引擎实施模式 ENFORCE 已评估并强制执行。可以屏蔽或修改请求。已评估但未强制执行。仅记录决策；引擎中的其他ACTIVE策略仍会强制执行。
LOG_ONLY 已评估但未强制执行。仅记录决策。已评估但未强制执行。仅记录决策。
**注意** 策略引擎强制模式优先。当策略引擎在 LOG\_ONLY 模式下关联时，任何策略都不能拒绝网关操作，即使是处于`ACTIVE`强制模式的策略也是如此，因为网关根本不会根据策略引擎的决策采取行动。引擎仍在计算决策，但你仍然会收到`LOG_ONLY`遥测数据；该决定根本没有得到执行。 ## 设置策略的执行模式 创建或更新策略时，可以在策略上设置该字段（即`CreatePolicy`和`UpdatePolicy`），该`enforcementMode`字段由`GetPolicy`和返回`ListPolicies`。 **在`LOG_ONLY`模式下创建策略**通过在`CreatePolicy`请求中设置为`enforcementMode`，`LOG_ONLY`在`LOG_ONLY`模式下创建策略。以下示例在政策中创建了一个护栏，禁止超过置信阈值的暴力内容，但只能遵守它。有关政策中的护栏的更多信息，请参阅策略中的[护栏](policy-guardrails-in-policies.md)。 ``` aws bedrock-agentcore-control create-policy \ --policy-engine-id my-policy-engine-id \ --name "LogOnlyViolenceFilter" \ --enforcement-mode LOG_ONLY \ --validation-mode IGNORE_ALL_FINDINGS \ --definition '{"policy":{"statement":"forbid (principal, action == AgentCore::Action::\"MyTarget\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.userMessage])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.7\")) };"}}' ``` 响应以 “EnforcementMode” 回应政策：“LOG\_ONLY”。该策略开始根据流量进行评估，从那时起，其匹配项就会出现在跟踪和 CloudWatch 指标中，而不会影响任何决策。 **列出策略及其实施模式** ListPolicies `enforcementMode`在每个策略摘要中都会返回，因此您可以一目了然地看到哪些策略正在遵守，哪些策略正在执行。 ``` aws bedrock-agentcore-control list-policies \ --policy-engine-id my-policy-engine-id \ --query 'policies[].{name:name,enforcementMode:enforcementMode,status:status}' ``` **响应** ``` [ { "name": "LogOnlyViolenceFilter", "enforcementMode": "LOG_ONLY", "status": "ACTIVE" }, { "name": "RefundLimit", "enforcementMode": "ACTIVE", "status": "ACTIVE" } ] ``` ## 观察 LOG\_ONLY 结果 当呼叫者通过网关发出 tools/call 请求时， AgentCore 网关会先评估所有策略（包括`LOG_ONLY`策略），然后将 MCP 响应返回给呼叫者。呼叫者的响应永远不会受到`LOG_ONLY`策略的影响；这些结果仅通过可观察性来报告。 您可以通过追踪和 Amazon CloudWatch 指标来观察`LOG_ONLY`政策行为： **跟踪和跨度：**当您在网关上启用跟踪时，策略评估跨度将包含`LOG_ONLY`匹配信息。你可以在 Obs AgentCore ervability 控制台中检查这些跨度，看看哪些`LOG_ONLY`策略是针对给定请求触发的，以及它们是否会推翻决定。有关更多信息，请参阅[在 Amazon Bedrock AgentCore 可观测性上观察您的代理应用程序](observability.md)。 CloudWatch AgentCore m@@ **etrics：**中的策略在 AWS/Bedrock-AgentCore 命名空间下发布指标。以下指标是特定于`LOG_ONLY`评估的： | 指标 | 它告诉你什么 | | --- | --- | | `ConfidenceScore`（用 PolicyEnforcementMode =`LOG_ONLY`） | 护栏为匹配`LOG_ONLY`的保单返回的信心分数。在选择阈值时，使用它来了解流量的分数分布。 | | `ConfidenceThreshold`（带有 `PolicyEnforcementMode=LOG_ONLY`） | 在`LOG_ONLY`策略上配置的阈值。在比较不同策略的分数和阈值时很有用。 | | `LogOnlyMatches` | `LOG_ONLY`策略触发的请求数。按策略发出，并作为引擎上所有`LOG_ONLY`策略的组汇总发出。 | | `LogOnlyDecisionFlips` | 如果`LOG_ONLY`策略被提升，本来会改变决策的请求数量。这是关键的促销信号：持续的零意味着推广该政策不会阻塞当前的流量。 | | `LogOnlyEvalIncomplete` | 在`LOG_ONLY`评估不完整时发出。使用它来警报持续存在的不完整评估率。 | 所有指标都包括 PolicyEngine 和用于筛选的 OperationName 维度。 Per-policy 指标还包括带有策略 ID 的策略维度。 有关查看 AgentCore 资源指标的更多信息，请参阅 B [edrock AgentCore 生成的可观测性](observability.md)数据。 ## 将政策推向执法 当您对某项`LOG_ONLY`政策充满信心时，请将其提升为强制执行`UpdatePolicy`，设置`enforcementMode`为`ACTIVE`。无需进行其他更改，并且该策略保留了其 ID、名称和定义。 ``` aws bedrock-agentcore-control update-policy \ --policy-engine-id my-policy-engine-id \ --policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \ --enforcement-mode ACTIVE ``` 反之亦然：你可以将`ACTIVE`政策向后移动，使其脱`LOG_ONLY`离执法，同时保持其原位并继续遵守该政策。 因此，典型的生命周期是在中创建策略`LOG_ONLY`，观察流量和指标，然后将其提升到`ACTIVE`，如果需要，`LOG_ONLY`可以在不删除和重新创建策略的情况下将其降级为。 ## 在 LOG\_ONLY 模式下选择阈值 `LOG_ONLY`模式对于护栏策略特别有用，在该策略中，您需要选择一个置信分数阈值，以平衡安全性与合法流量中断之间的关系。阈值过低会阻止合法请求；过高的阈值可能会让威胁通过。 **推荐的工作流程：**在您认为合理的阈值（例如 0.7）的`LOG_ONLY`模式下部署护栏。该策略会评估每个请求并对 CloudWatch 指标发出置信度分数，但从不阻止流量。 通过具有代表性的窗口（几天或几周的实际生产流量）积累数据。该 ConfidenceScore 指标（带有 PolicyEnforcementMode =LOG\_ONLY）为您提供流量产生的分数分布。 根据真实情况分析分数。如果您有标记的测试集（提示标记为良性或恶意），则可以在每个阈值下计算精度和召回率，然后选择最符合目标的测试集。如果您没有已标记的数据，请从高分范围（例如 0.8—1.0）、低分范围（0—0.2）和模糊的中间区域（0.4—0.7）中采样提示，然后对每个样本进行分类，以建立对阈值选择的信心。使用您选择的阈值更新政策，并将其提升为`ACTIVE`： ``` aws bedrock-agentcore-control update-policy \ --policy-engine-id my-policy-engine-id \ --policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \ --enforcement-mode ACTIVE \ --definition '{"policy":{"statement":"forbid (principal, action == AgentCore::Action::\"MyTarget\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.userMessage])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.65\")) };"}}' ``` 此工作流程可确保阈值反映您的实际流量模式，而不是一般的默认值。 ## 注意事项和限制 `LOG_ONLY`政策永远不会影响决策。`LOG_ONLY`策略不能导致允许或拒绝某项操作。请求收到的决定与在`LOG_ONLY`政策不存在时收到的决定相同。这是该功能的核心保障。 更改最终是一致的。创建、更新或升级策略将在几秒钟内应用于评估路径。相应地规划您的观察窗口和晋升步骤，而不是指望瞬间切换。 结果列表是有界限的。 `LOG_ONLY`匹配列表和决策翻转列表每个请求上限为 1,000 个条目。对于拥有大量`LOG_ONLY`策略的引擎，请依靠这些 CloudWatch 指标来获得完整的汇总计数。 评估可以是部分的。当请求的`LOG_ONLY`评估未完成时，该请求的`LOG_ONLY`信号可能缺少条目。强制执行的决定永远不会受到影响。