LOG_ONLY 模式的工作原理 LOG_ONLY 策略和 LOG_ONLY 策略引擎设置策略的执行模式观察 LOG_ONLY 结果将政策推向执法使用 LOG_ONLY 模式选择阈值注意事项和限制

在 LOG_ONLY 模式下测试策略

使用策略级执行模式，您可以在ACTIVE和之间切换LOG_ONLY以回答以下问题：“如果应用此政策，它将对我的流量产生什么影响？” 每策略LOG_ONLY模式允许您在不影响授权决策的情况下根据实际流量测试策略。该策略会像强制执行一样评估每个请求，但仅将结果写入日志。任何内容都不会因为执行模式为的政策而被封锁或允许LOG_ONLY。一旦您信任了结果，就将其推广到ACTIVE。

LOG_ONLY 模式的工作原理

策略引擎中的每个策略的执行模式均为ACTIVE或LOG_ONLY。默认值为ACTIVE，因此现有策略以及您在未指定字段的情况下创建的任何新策略将继续像以前一样强制执行。当策略引擎评估请求时，它会并行评估您的ACTIVE策略和LOG_ONLY策略，但仅对您的策略强制执行。ACTIVE

ACTIVE策略决定将决策退回给 AgentCore 网关并强制执行。策略引擎采用 “default-deny” 和 “forbid-wins” 语义，这意味着只有在策略允许的情况下才允许请求，而任何活动策略的单个禁令都会拒绝该请求。

LOG_ONLY根据相同的请求对策略进行评估，但其结果是分开的。它们以追踪形式报告并作为亚马逊 CloudWatch 指标发布。它们永远不会合并到强制执行的决定中。

执法模式	对每个请求进行了评估？	影响退回的决定吗？
`ACTIVE`（默认值）	支持	是
`LOG_ONLY`	是	否

请求分两个阶段进行评估：

策略引擎计算决策。只有ACTIVE政策才有助益。LOG_ONLY政策是单独评估和报告的，但从不考虑在内。
如果引擎与ENFORCE模式下的网关关联，则网关根据策略引擎的决定允许或拒绝该操作。如果引擎在LOG_ONLY模式下与网关关联，则网关不采取任何操作；决策会被记录但不强制执行。

ACTIVE并LOG_ONLY被视为两个孤立的集合；一项LOG_ONLY政策永远无法改变您的来电者的体验。请求收到的决定不受任何LOG_ONLY政策的影响。

除了记录与请求相匹配的LOG_ONLY策略外，策略引擎还会报告如果是，哪些策略会更改决策ACTIVE。这是评估政策的有效性和安全性（即是否可以推广ACTIVE）时使用的关键信号。例如，经常匹配并出现在决策反向集合中的LOG_ONLY策略将在观察窗口期间阻止您的流量。每项LOG_ONLY策略的评估独立于所有其他LOG_ONLY政策，以确定一组决策转变政策。但是，每项LOG_ONLY政策评估都会考虑所有当前的ACTIVE政策。

LOG_ONLY 策略和 LOG_ONLY 策略引擎

中的策略 AgentCore 有两个单独的控件，它们都使用值 LOG_ONLY。它们在不同的层面上运行，回答不同的问题，因此了解你在设置哪个层面很重要。

策略引擎实施模式：控制引擎的整体行为。如果设置为LOG_ONLY，则无论其单个策略模式如何，引擎中都不会强制执行任何策略。所有决定都记录在案。policyEngineConfiguration当您使用CreateGateway或UpdateGateway操作将策略引擎与网关关联时，使用的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模式下创建策略。以下示例在政策中创建了护栏，该护栏禁止超过可信度阈值的暴力内容，但仅对其进行观察。有关策略中护栏的更多信息，请参阅策略中的护栏。


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\")) };"}}'

该回应以 “强制模式”：“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政策的影响；这些结果仅通过可观察性进行报告。

您可以通过追踪和亚马逊 CloudWatch 指标观察LOG_ONLY政策行为：

跟踪和跨度：当您在网关上启用跟踪时，策略评估跨度包括LOG_ONLY匹配信息。你可以在 Obs AgentCore ervability 控制台中检查这些跨度，看看哪些LOG_ONLY策略是针对给定请求触发的，以及它们是否会推翻决定。有关更多信息，请参阅在 Amazon Bedrock AgentCore 可观测性上观察您的代理应用程序。

CloudWatch 指标：中的策略在 AgentCore 命名 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 生成的可观测性数据。

将政策推向执法

当你对某项LOG_ONLY政策充满信心时，将其推广到强制执行UpdatePolicy，设置为enforcementModeACTIVE。无需进行其他更改，策略保留其 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信号可能缺少条目。强制执行的决定永远不会受到影响。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

验证和测试策略

验证和分析概述