管理指南

1. 创建接收事件的服务器进程
2. 扩展 OpenShift Dev Spaces 库，以创建将事件发送到服务器的后端
3. 在容器中打包遥测后端并将其部署到镜像 registry
4. 为您的后端添加插件，并指示 OpenShift Dev Spaces 加载 Dev Workspaces 中的插件

1. Maven Quarkus 项目构建：

   mvn io.quarkus:quarkus-maven-plugin:2.7.1.Final:create \
       -DprojectGroupId=mygroup -DprojectArtifactId=devworkspace-telemetry-example-plugin \
   -DprojectVersion=1.0.0-SNAPSHOT

2. 删除 src/main/java/mygroup 和 src/test/java/mygroup 下的文件。
3. 有关 backend-base 的最新版本，请参阅 GitHub 软件包。

4. 在 pom.xml 中添加以下依赖项：

   例 3.13. pom.xml

   <!-- Required -->
   <dependency>
       <groupId>org.eclipse.che.incubator.workspace-telemetry</groupId>
       <artifactId>backend-base</artifactId>
       <version>LATEST VERSION FROM PREVIOUS STEP</version>
   </dependency>
   
   
   <!-- Used to make http requests to the telemetry server -->
   <dependency>
       <groupId>io.quarkus</groupId>
       <artifactId>quarkus-rest-client</artifactId>
   </dependency>
   <dependency>
       <groupId>io.quarkus</groupId>
       <artifactId>quarkus-rest-client-jackson</artifactId>
   </dependency>

5. 创建一个具有 read:packages 权限的个人访问令牌，以便从 GitHub 软件包下载 org.eclipse.che.incubator.workspace-telemetry:backend-base 依赖项。

6. 在 ~/.m2/settings.xml 文件中添加 GitHub 用户名、个人访问令牌和 che-incubator 存储库详情：

   例 3.14. settings.xml

   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
   http://maven.apache.org/xsd/settings-1.0.0.xsd">
      <servers>
         <server>
            <id>che-incubator</id>
            <username>YOUR GITHUB USERNAME</username>
            <password>YOUR GITHUB TOKEN</password>
         </server>
      </servers>
   
      <profiles>
         <profile>
            <id>github</id>
            <activation>
               <activeByDefault>true</activeByDefault>
            </activation>
            <repositories>
               <repository>
                  <id>central</id>
                  <url>https://repo1.maven.org/maven2</url>
                  <releases><enabled>true</enabled></releases>
                  <snapshots><enabled>false</enabled></snapshots>
                  </repository>
                  <repository>
                  <id>che-incubator</id>
                  <url>https://maven.pkg.github.com/che-incubator/che-workspace-telemetry-client</url>
               </repository>
            </repositories>
         </profile>
      </profiles>
   </settings>

1. 在 Dev Workspace 中设置 DEVWORKSPACE_TELEMETRY_BACKEND_PORT 环境变量。此处，值设为 4167。

   spec:
     template:
       attributes:
         workspaceEnv:
           - name: DEVWORKSPACE_TELEMETRY_BACKEND_PORT
             value: '4167'

2. 从 Red Hat OpenShift Dev Spaces 仪表板中重启 Dev Workspace。

3. 在 Dev Workspace 的终端窗口中运行以下命令以启动应用程序。使用 --settings 标志指定包含 GitHub 访问令牌的 settings.xml 文件的位置的路径。

   $ mvn --settings=settings.xml quarkus:dev -Dquarkus.http.port=${DEVWORKSPACE_TELEMETRY_BACKEND_PORT}

   应用程序现在通过前端插件的端口 4167 接收遥测事件。

验证步骤

1. 验证以下输出是否已记录：

   INFO  [org.ecl.che.inc.AnalyticsManager] (Quarkus Main Thread) No welcome message provided
   INFO  [io.quarkus] (Quarkus Main Thread) devworkspace-telemetry-example-plugin 1.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 0.323s. Listening on: http://localhost:4167
   INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
   INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, kubernetes-client, rest-client, rest-client-jackson, resteasy, resteasy-jsonb, smallrye-context-propagation, smallrye-openapi, swagger-ui, vertx]

2. 要验证 AnalyticsManager 的 onEvent （） 方法是否从前端插件接收事件，请按 l 键来禁用 Quarkus 实时编码并编辑 IDE 中的任何文件。应记录以下输出：

   INFO  [io.qua.dep.dev.RuntimeUpdatesProcessor] (Aesh InputStream Reader) Live reload disabled
   INFO  [org.ecl.che.inc.AnalyticsManager] (executor-thread-2) The received event is: Edit Workspace File in Che

1. 通过创建 TelemetryService.java来设置 RESTEasy REST 客户端

   例 3.19. TelemetryService.java

   package org.my.group;
   
   import java.util.Map;
   
   import javax.ws.rs.Consumes;
   import javax.ws.rs.POST;
   import javax.ws.rs.Path;
   import javax.ws.rs.core.MediaType;
   import javax.ws.rs.core.Response;
   
   import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
   
   @RegisterRestClient
   public interface TelemetryService {
       @POST
       @Path("/event") 

   1

   
       @Consumes(MediaType.APPLICATION_JSON)
       Response sendEvent(Map<String, Object> payload);
   }

   1

   发出请求 的端点。

2. 在 src/main/resources/application.properties 文件中指定 TelemetryService 的基本 URL：

   例 3.20. application.properties

   org.my.group.TelemetryService/mp-rest/url=http://little-telemetry-server-che.apps-crc.testing

3. 将 TelemetryService 注入 AnalyticsManager，并在 onEvent （）中发送 POST 请求

   例 3.21. AnalyticsManager.java

   @Dependent
   @Alternative
   public class AnalyticsManager extends AbstractAnalyticsManager {
       @Inject
       @RestClient
       TelemetryService telemetryService;
   
   ...
   
   @Override
   public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, Map<String, Object> properties) {
       Map<String, Object> payload = new HashMap<String, Object>(properties);
       payload.put("event", event);
       telemetryService.sendEvent(payload);
   }

   这会向遥测服务器发送 HTTP 请求，并在少量时间内自动延迟相同的事件。默认持续时间为 1500 毫秒。

1. 在现有 Dev Workspace 的 components 字段中添加以下内容：

   components:
     ...
     - name: telemetry-plugin
       plugin:
         uri: http://apache-che.apps-crc.testing/plugin.yaml

2. 从 OpenShift Dev Spaces 仪表板启动 Dev Workspace。

验证步骤

1. 验证遥测插件容器是否在 Dev Workspace pod 中运行。在这里，这可以通过检查编辑器中的 Workspace 视图进行验证。

   
2. 编辑编辑器中的文件，并在示例遥测服务器日志中观察其事件。

验证步骤

1. 从 Red Hat OpenShift Dev Spaces 仪表板中启动一个新的或现有的 Dev Workspace。
2. 按照 第 3.6.1.6.12 节 “在 Dev Workspace 中指定 telemetry 插件” 的验证步骤，验证遥测插件是否正常工作。

流程

1. 创建一个 ClusterRoleBinding，将与 Prometheus 关联的 ServiceAccount 绑定到 devworkspace-controller-metrics-reader ClusterRole。对于 监控堆栈示例，要使用的 ServiceAccount 的名称是 prometheus。

   注意

   如果没有 ClusterRoleBinding，您无法访问 Dev Workspace 指标，因为访问使用基于角色的访问控制(RBAC)进行保护。

   例 3.31. ClusterRoleBinding

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: devworkspace-controller-metrics-binding
   subjects:
     - kind: ServiceAccount
       name: prometheus
       namespace: monitoring
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: devworkspace-controller-metrics-reader

2. 将 Prometheus 配置为从 devworkspace-controller-metrics Service 公开的端口 8443 中提取指标，并从 devworkspace-webhookserver 服务公开的端口 9443 中提取指标。

   注意

   监控堆栈示例 已创建了带有空配置的 prometheus-config ConfigMap。要提供 Prometheus 配置详情，请编辑 ConfigMap 的 data 字段。

   例 3.32. Prometheus 配置

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: prometheus-config
     namespace: monitoring
   data:
     prometheus.yml: |-
         global:
           scrape_interval: 5s 

   1

   
           evaluation_interval: 5s 

   2

   
         scrape_configs: 

   3

   
           - job_name: 'DevWorkspace'
             scheme: https
             authorization:
               type: Bearer
               credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token'
             tls_config:
               insecure_skip_verify: true
             static_configs:
               - targets: ['devworkspace-controller-metrics.<DWO_project>:8443'] 

   4

   
           - job_name: 'DevWorkspace webhooks'
             scheme: https
             authorization:
               type: Bearer
               credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token'
             tls_config:
               insecure_skip_verify: true
             static_configs:
               - targets: ['devworkspace-webhookserver.<DWO_project>:9443'] 

   5

   1

   提取目标的速度。

   2

   重新检查记录和警报规则的速度。

   3

   Prometheus 监控的资源。在默认配置中，两个作业是 DevWorkspace 和 DevWorkspace Webhook，提取 devworkspace-controller-metrics 和 devworkspace-webhookserver 服务公开的时间序列数据。

   4

   从端口 8443 获取指标的目标。将 <DWO_project> 替换为 devworkspace-controller-metrics Service 所在的项目。

   5

   从端口 9443 获取指标的目标。将 <DWO_project> 替换为 devworkspace-webhookserver Service 所在的项目。

3. 缩减 Prometheus Deployment，再读取上一步中的更新 ConfigMap。

   $ oc scale --replicas=0 deployment/prometheus -n monitoring && oc scale --replicas=1 deployment/prometheus -n monitoring

验证

1. 使用端口转发在本地访问 Prometheus Service：

   $ oc port-forward svc/prometheus 9090:9090 -n monitoring

2. 通过查看 localhost:9090/targets 上的目标端点来验证所有目标是否已启动。

3. 使用 Prometheus 控制台查看和查询指标：

   • 查看 localhost:9090/metrics 的指标。

   • 从 localhost 查询指标：9090/graph.

     如需更多信息 ，请参阅使用表达式浏览器。

流程

1. 为 Prometheus 实例添加数据源。请参阅创建 Prometheus 数据源。
2. 导入 grafana-dashboard.json 仪表板示例。

流程

1. 配置 Prometheus，以从端口 8087 中提取指标。

   注意

   监控堆栈示例 已创建了带有空配置的 prometheus-config ConfigMap。要提供 Prometheus 配置详情，请编辑 ConfigMap 的 data 字段。

   例 3.33. Prometheus 配置

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: prometheus-config
   data:
     prometheus.yml: |-
         global:
           scrape_interval:     5s             

   1

   
           evaluation_interval: 5s             

   2

   
         scrape_configs:                       

   3

   
           - job_name: 'OpenShift Dev Spaces Server'
             static_configs:
               - targets: ['che-host.<OpenShift Dev Spaces_project>:8087']  

   4

   1

   提取目标的速度。

   2

   重新检查记录和警报规则的速度。

   3

   Prometheus 监控的资源。在默认配置中，单个作业 OpenShift Dev Spaces 服务器 提取 OpenShift Dev Spaces 服务器公开的时间序列数据。

   4

   从端口 8087 获取指标的目标。将 <OpenShift Dev Spaces_project& gt; 替换为 OpenShift Dev Spaces 项目。默认 OpenShift Dev Spaces 项目为 openshift-devspaces。

2. 缩减 Prometheus Deployment，再读取上一步中的更新 ConfigMap。

   $ oc scale --replicas=0 deployment/prometheus -n monitoring && oc scale --replicas=1 deployment/prometheus -n monitoring

验证

1. 使用端口转发在本地访问 Prometheus Service：

   $ oc port-forward svc/prometheus 9090:9090 -n monitoring

2. 通过查看 targets 端点（位于localhost:9090/targets）来验证所有目标已在线。

3. 使用 Prometheus 控制台查看和查询指标：

   • 查看 localhost:9090/metrics 的指标。

   • 从 localhost 查询指标：9090/graph.

     如需更多信息 ，请参阅使用表达式浏览器。

流程

1. 为 Prometheus 实例添加数据源。请参阅创建 Prometheus 数据源。
2. 导入示例 仪表板。请参阅导入仪表板。

3. 在 Grafana 控制台中查看 OpenShift Dev Spaces JVM 指标：

   图 3.4. OpenShift Dev Spaces 服务器 JVM 仪表板

   

   图 3.5. 快速事实

   

   图 3.6. JVM 内存

   

   图 3.7. JVM Misc

   

   图 3.8. JVM 内存池（堆）

   

   图 3.9. JVM 内存池(Non-Heap)

   

   图 3.10. 垃圾回收

   

   图 3.11. 类加载

   

   图 3.12. 缓冲池

   

流程

1. 进入 https://github.com/settings/applications/new。

2. 输入以下值：

   1. 应用程序名称 ：OpenShift Dev Spaces
   2. 主页 URL:https://devspaces- <openshift_deployment_name>. <domain_name>/
   3. 授权回调 URL:https://devspaces- &lt;openshift_deployment_name>.<domain_name&gt; /api/oauth/callback
3. 点击 Register application。
4. 点 Generate new client secret。

5. 复制 GitHub OAuth 客户端 ID，并将其编码到 Base64 中，以便在应用 GitHub OAuth App Secret 时要使用的：

   $ echo -n '<github_oauth_client_id>' | base64

6. 复制 GitHub OAuth 客户端 Secret，并将其编码到 Base64 中，以便在应用 GitHub OAuth App Secret 时要使用的：

   $ echo -n '<github_oauth_client_secret>' | base64

流程

1. 准备 Secret：

   kind: Secret
   apiVersion: v1
   metadata:
     name: github-oauth-config
     namespace: openshift-devspaces 

   1

   
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: oauth-scm-configuration
     annotations:
       che.eclipse.org/oauth-scm-server: github
       che.eclipse.org/scm-server-endpoint: <github_server_url> 

   2

   
   type: Opaque
   data:
     id: <Base64_GitHub_OAuth_Client_ID> 

   3

   
     secret: <Base64_GitHub_OAuth_Client_Secret> 

   4

   1

   OpenShift Dev Spaces 命名空间。默认值为 openshift-devspaces。

   2

   GitHub Enterprise Server URL。默认情况下 ，https://github.com 用于 SAAS 版本。

   3

   Base64 编码的 GitHub OAuth 客户端 ID。

   4

   Base64 编码的 GitHub OAuth 客户端机密。

2. 应用 Secret：

   $ oc apply -f - <<EOF
   <Secret_prepared_in_the_previous_step>
   EOF

3. 验证在 Secret 是否已创建的输出中。