配置高级 Cryostat 配置

您可以使用可插拔发现 API 端点 /api/v2.2/discovery，将外部插件注册到 Cryostat，然后提供有关可发现的应用程序目标的信息。在成功注册 Cryostat 后，一个插件可以取消注册自身，或持续将更新推送到有关目标应用程序的 Cryostat。

可插拔的 Discovery API 提供了更灵活的方法，用于将 Cryostat 集成到 Red Hat OpenShift 服务帐户机制的部署模式中。

例如，您需要编写插件程序来创建应用程序 IP 地址到端口号的静态映射。该插件可以使用可插拔发现 API 将此信息传送到 Cryostat，以便 Cryostat 能够更好地与目标应用程序连接。

Pluggable Discovery API 依赖于以下处理程序来管理从 /api/v2.2/discovery 端点和 Cryostat 发送的请求：

在使用 API 的端点与 Cryostat 交互前，您必须确保客户端（即插件的来源）符合以下先决条件：

如果需要使用 Cryostat 注册您自己的发现插件程序，您可以禁用 Cryostat 内置发现机制。禁用内置发现机制有助于减少在 Cryostat web 控制台中打开的重复定义（如果插件和 Cryostat 都可以访问相同的目标应用程序信息）。

您可以在 Red Hat OpenShift 命令行控制台(CLI)中设置以下环境变量来禁用 Cryostat 内置发现机制：

CRYOSTAT_DISABLE_BUILTIN_DISCOVERY=true

您还可以考虑保留 Cryostat 内置发现实现的设置，然后完成以下操作之一：

Pluggable Discovery API 使用 DisoveryRegistrationHandler 注册发现插件的 Cryostat。该处理程序管理来自插件和 Cryostat 的 GET 和 POST 请求。如果您没有使用 Cryostat 注册插件，则插件无法向 Cryostat 提供目标信息。

当发现插件程序向 Cryostat 发送 POST 请求以注册时，C Cryostat 会读取 回调 URL，并将 GET 请求发送到插件。如果插件正确响应 GET 请求，则 Cryostat 会响应初始 POST 请求来接受注册请求。这个过程确保插件处于活跃状态，并可用于 Cryostat。

失败的请求可能表示插件失败或离线。在这种情况下，端点会从 Red Hat OpenShift 上的数据库中删除插件的信息。

您还可以在 GET 或 POST 请求中指定 id 和令牌 元素。这些元素是可选的，但您可以在想要为之前使用 Cryostat 注册的插件重复使用注册信息的情况。

Cryostat 为注册插件创建一个令牌，此令牌包含到期和授权信息。如果 POST 请求包含有效的 id 和令牌 信息，C Cryostat 可以重复使用插件注册信息并刷新令牌。如果请求只包含 id 元素 或令牌 元素，则必须将插件重新注册到 Cryostat。

在 Cryostat 发送 POST 请求到插件 的回调 组件后，该插件可能会向 Cryostat 发送 POST 请求以刷新插件的注册详情。该插件必须将其 id 和令牌 信息包含在其请求中。然后 Cryostat 可以使用 DiscoveryRegistrationHandler 刷新插件的详细信息。Cryostat 发送包含更新令牌到插件的响应，插件就可以使用这个令牌到 Cryostat。

{
    "realm": "my-plugin",
    "callback": "http://my-plugin.my-namespace.svc.local:1234/callback"
}

{
"data": {
    "result": {
        "id": "922dd4f4-9d7c-4ae2-8982-0903868226a6",
        "token": "<key_value>"
    }
},
"meta": {
    "status": "Created",
    "type": "application/json"
}

可插拔发现 API 使用 DisoveryRegistrationCheckHandler 处理程序使插件在 Cryostat 服务器实例上定期检查自己的注册状态。

DisoveryRegistrationCheckHandler 处理程序管理插件到 Cryostat 的 GET 请求。通过使用处理程序，外部插件可以定期验证已注册到的 Cryostat 服务器实例，它们仍然处于活动状态，并识别插件之前注册。

与 Cryostat 回调 URL 端点检查插件实例的方式类似，其中 Cryostat 读取 回调 URL 并向插件发送 GET 请求，DisoveryRegistrationCheckHandler 处理程序的工作方式相同，但以相反方向发送请求。也就是说，插件向 Cryostat 服务器发送 GET 请求，以检查 Cryostat 服务器上的注册状态。如果请求失败，例如，如果收到了 未预期的 401 或 Unexpected 404 错误响应，插件可以丢弃它现有的注册信息，并尝试再次注册。

$ http -v https://my-cryostat.my-namespace.cluster.local:8181/api/v2.2/discovery/<plugin-registration-id>?token=<current-plugin-registration-token>

HTTP/1.1 200 OK
content-encoding: gzip
content-length: 86
content-type: application/json

{
	"data": {
    	"result": null
	},
	"meta": {
    	"mimeType": "JSON",
    	"status": "OK"
	}
}

HTTP/1.1 404 Not Found
content-encoding: gzip
content-length: 95
content-type: application/json

{
	"data": {
    	"reason": null
	},
	"meta": {
    	"status": "Not Found",
    	"type": "text/plain"
	}
}

DiscoveryGetHandler 封装部署模式并在分层树视图中打开这些架构，以便 Cryostat 可以与任何已注册的可发现插件交互，以便与特定的部署模式集成。

当您创建至少一个 pod 的部署，服务映射到 Red Hat OpenShift 上的部署或 pod 时，Red Hat OpenShift 会为 Pod IP 地址和端口的所有组合创建一个端点对象 /api/v2.2/discovery。DiscoveryGetHandler 从端点 GET 请求接收信息，然后以 JSON 格式合作部署模式信息。

以下示例演示了处理程序如何在 JSON 格式以分级树视图中打开。在示例中，树根是 UNIVERSE 节点。此节点包含子 Realm 节点类型，它源自 Cryostat 的内置发现机制以及 Pluggable Discovery API 发现的插件。

{
    "data": {
        "result": {
            "children": [
                {
                    "children": [],
                    "labels": {},
                    "name": "Custom Targets",
                    "nodeType": "Realm"
                },
                {
                    "children": [
                        {
                            "labels": {},
                            "name": "service:jmx:rmi:///jndi/rmi://cryostat:9091/jmxrmi",
                            "nodeType": "JVM",
                            "target": {
                                "alias": "io.cryostat.Cryostat",
                                "annotations": {
                                    "cryostat": {
                                        "HOST": "cryostat",
                                        "JAVA_MAIN": "io.cryostat.Cryostat",
                                        "PORT": "9091",
                                        "REALM": "JDP"
                                    },
                                    "platform": {}
                                },
                                "connectUrl": "service:jmx:rmi:///jndi/rmi://cryostat:9091/jmxrmi",
                                "labels": {}
                            }
                        }
                    ],
                    "labels": {},
                    "name": "JDP",
                    "nodeType": "Realm"
                }
            ],
            "labels": {},
            "name": "Universe",
            "nodeType": "Universe"
        }
    },
    "meta": {
        "status": "OK",
        "type": "application/json"
    }
}

通过 Cryostat 注册的插件会发送 POST /api/v2.2/discovery/:id 请求到 DiscoveryPostHandler。请求的 id 参数引用注册插件的 ID。此处理程序处理与插件关联的任何子树，然后映射部署架构。

Cryostat POST 请求定义了一个子树 REALM 节点，因此插件处理程序可以在请求过程中在 REALM 节点中发布其子节点类型。该插件负责为Cryostat REALM 节点提供正确的信息，并将节点类型放入正确的子树位置。该插件必须为令牌提供它发送到 DiscoveryPostHandler 的 POST 请求，以便插件可以绕过之前通过的授权标头检查。

[
    {
        "labels": {},
        "nodeType": "JVM",
        "name": "service:jmx:rmi:///jndi/rmi://myapp.svc.local:9091/jmxrmi",
        "nodeType": "JVM",
        "target": {
            "alias": "com.MyApp",
            "annotations": {
                "cryostat": {},
                "platform": {}
        },
            "connectUrl": "service:jmx:rmi:///jndi/rmi://myapp.svc.local:9091/jmxrmi",
            "labels": {}
        }
    }
]

{
    "data": {
        "result": null
    },
    "meta": {
        "mimeType": "JSON",
        "status": "OK"
    }
}

如果一个插件使用 Cryostat 作为 插件 注册，则插件需要关闭，插件通常会向 un-register 本身作为一个 插件 发出请求。Cryostat 发送 DELETE /api/v2.2/discovery/:id?token=:token 请求到 DiscoveryDeregistrationHandler，然后从 Cryostat 取消注册插件。

该处理程序从发现模式删除插件的 REALM 子树，以及插件的注册信息（来自 Cryostat）。

{
     "data": {
        "result": "bcc0f3a6-dc48-402e-a3d6-9fbb63beff78"
    },
    "meta": {
        "mimeType": "JSON",
        "status": "OK"
    }
}

当插件通过 Cryostat 注册插件时，可插拔发现 API 会返回消息。

当处理程序试图根据 GET 和 POST 请求注册带有 Cryostat 的插件时，处理程序可以返回以下消息类型：

您可以使用 HTTP 客户端（如 HTTPie ）与 GraphQL API 交互来生成自定义查询。

当使用 API 创建查询时，您必须为数据类型和字段指定特定值，以便函数可以使用这些值来准确定位所需数据。

考虑一个用例，您可以在其中自动执行在单个查询中执行多个操作的工作流。例如，HTTPie 客户端请求可能会向 Cryostat 发送查询，以便 Cryostat 可以执行以下任务：

以下示例演示了使用 HTTP 客户端与 GraphQL API 交互，以在 Cryostat 数据上生成简单查询和复杂的查询。

$ https :8181/api/v1/targets
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 223
content-type: application/json

 {
	targetNodes {
    		name
    		nodeType
    		labels
    		target {
        		alias
        		serviceUri
    		}
	}
}

上例为 targetNodes 元素设置特定的值，如名称。运行查询后，查询会返回与指定条件匹配的任何目标 JVM 列表。

$ https -v :8181/api/v2.2/graphql query=@graphql/target-nodes-query.graphql
POST /api/v2.2/graphql HTTP/1.1
Accept: application/json, /;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 171
Content-Type: application/json
Host: localhost:8181
User-Agent: HTTPie/2.6.0

 {
environmentNodes(filter: { name: "<application_pod_name>" }) {
    		descendantTargets {
        		doStartRecording(recording: {
            		name: "myrecording",
            	template: "Profiling",
            	templateType: "TARGET",
     		       	duration: 30
          	 	}) {
          			name
          			state
        		}
    		}
	}
}

上例为 environmentNodes 元素设置以下特定值，示例不会返回 JVM 目标应用：

运行查询后，查询会返回有关您启动的 JFR 记录的信息，如活跃应用程序节点列表。

对于 Red Hat OpenShift，此查询会返回 Deployment 和 DeploymentConfig API 对象，以及与 Cryostat 交互的 pod。

复杂的查询演示了 GraphQL API 如何执行单个 API 请求，该请求返回与 Cryostat 和 Red Hat OpenShift 交互的任何 JVM 对象。然后，API 请求会在这些返回的对象上启动 JFR 记录。

Cryostat 与 JMC Agent 相结合，您可以在需要诊断正在运行的 JVM 应用问题时为您提供更多信息。

JMC Agent JAR 文件必须与目标 JVM 应用程序位于同一个 Red Hat OpenShift 容器中。否则，Cryostat 无法在应用程序中使用 JMC Agent 功能。

从 Cryostat Web 控制台，您可以上传探测模板，然后将这些模板插入到 JVM 应用中。如果需要，您可以在稍后阶段删除这些模板探测。探测模板描述了 Cryostat 可以处理的一组对象，以便 Cryostat 可以完成 JVM 应用中的 JMC Agent 操作序列。

当使用 JMC Agent 启动目标 JVM 应用程序时，Cryostat 会自动检测应用程序是否使用 JMC Agent 运行。

更新于 2024-01-02