3.6. 可観測性の設定


OpenShift Dev Spaces 可観測性機能を設定するには、以下を参照してください。

3.6.1. Che-Theia ワークスペース

3.6.1.1. Telemetry の概要

Telemetry は、操作データの明示的かつ論理的なコレクションです。デフォルトで、Telemetry は Red Hat OpenShift Dev Spaces では利用できませんが、Che-Theia エディターにはプラグインメカニズムを使用し、chectl コマンドラインツールの使用データをセグメントを使用して収集できる抽象 API があります。このアプローチは、すべての Che-Theia ワークスペースでテレメトリーが有効になっている Eclipse Che hosted by Red Hat サービスで使用されます。

以下では、Red Hat OpenShift Dev Spaces に独自の Telemetry クライアントを作成する方法について説明し、次に Red Hat OpenShift Dev Spaces Woopra Telemetry プラグイン の概要を示します。

3.6.1.2. ユースケース

Red Hat OpenShift Dev Spaces Telemetry API では、以下の追跡が可能です。

  • ワークスペース使用の期間
  • ファイルの編集、コミット、およびリモートリポジトリーへのプッシュなどのユーザー駆動型アクション
  • ワークスペースで使用されるプログラミング言語および devfile

3.6.1.3. 仕組み

Dev Workspace が起動すると、che-theia コンテナーは、テレメトリーイベントをバックエンドに送信するロールを担うテレメトリープラグインを起動します。$DEVWORKSPACE_TELEMETRY_BACKEND_PORT 環境変数が DevWorkspacePod で設定されている場合、テレメトリープラグインはそのポートでリッスンしているバックエンドにイベントを送信します。バックエンドは、受信したイベントをイベントのバックエンド固有の表現に変換し、設定された分析バックエンド (Segment や Woopra など) に送信します。

telemetry diagram

3.6.1.4. Che-Theia Telemetry プラグインによってバックエンドに送信されるイベント

イベント説明

WORKSPACE_OPENED

Che-Theia の起動時に送信されます。

COMMIT_LOCALLY

git.commitTheia コマンドを使用してローカルでコミットが行われたときに送信されます

PUSH_TO_REMOTE

git.push Theia コマンドで Git のプッシュが実行される際に送信されます。

EDITOR_USED

エディターでファイルが変更されたときに送信されます

WORKSPACE_INACTIVEWORKSPACE_STOPPED などの他のイベントは、バックエンドプラグイン内で検出できます。

3.6.1.5. Woopra telemetry プラグイン

Woopra Telemetry プラグイン は、Telemetry を Red Hat OpenShift Dev Spaces インストールから Segment および Woopra に送信するためにビルドされたプラグインです。このプラグインは、Red Hat がホストする Eclipse Che で使用されますが、Red Hat OpenShift Dev Spaces デプロイメントではこのプラグインを利用できます。有効な Woopra ドメインおよびセグメント書き込みキー以外の依存関係はありません。プラグインである plugin.yaml の devfile v2 には、プラグインに渡すことのできる 4 つの環境変数があります。

  • WOOPRA_DOMAIN - イベントの送信先となる Woopra ドメイン。
  • SEGMENT_WRITE_KEY - セグメントおよび Woopra にイベントを送信するための書き込みキー。
  • WOOPRA_DOMAIN_ENDPOINT - Woopra ドメインを直接渡さない場合、プラグインは Woopra ドメインを返す指定の HTTP エンドポイントからこれを取得します。
  • SEGMENT_WRITE_KEY_ENDPOINT - セグメント書き込みキーを直接渡さない場合、プラグインはセグメント書き込みキーを返す指定された HTTP エンドポイントからこれを取得します。

Red Hat OpenShift Dev Spaces インストールで Woopra プラグインを有効にするには、以下を実行します。

手順

  • plugin.yaml devfile v2 ファイルを、環境変数が正しく設定された HTTP サーバーにデプロイします。

    1. CheCluster カスタムリソースを設定します。「CLI を使用して CheCluster カスタムリソースの設定」を参照してください。

      spec:
        devEnvironments:
          defaultPlugins:
          - editor: eclipse/che-theia/next     1
            plugins:                           2
            - 'https://your-web-server/plugin.yaml'
      1
      テレメトリープラグインを設定するための editorId
      2
      Telemetry プラグインの devfile v2 定義への URL。

3.6.1.6. Telemetry プラグインの作成

本セクションでは、AbstractAnalyticsManager を拡張し、以下のメソッドを実装する AnalyticsManager クラスを作成する方法を説明します。

  • isEnabled(): Telemetry バックエンドが正しく機能しているかどうかを判断します。これは、常に true を返すか、または接続プロパティーがない場合に false を返すなど、より複雑なチェックがあることを意味します。
  • destroy(): Telemetry バックエンドをシャットダウンする前に実行されるクリーンアップ方法。このメソッドは、WORKSPACE_STOPPED イベントを送信します。
  • onActivity() - 特定のユーザーについて一部のアクティビティーが依然として実行されていることを通知します。これは主に WORKSPACE_INACTIVE イベントを送信するために使用されます。
  • onEvent() - Telemetry イベントを WORKSPACE_USED または WORKSPACE_STARTED などの Telemetry サーバーに送信します。
  • increaseDuration() - 短時間に多くのイベントを送信するのではなく、現在のイベントの期間を長くします。

次のセクションでは、以下について説明します。

  • Telemetry サーバーを作成してイベントを標準出力にエコーします。
  • OpenShift Dev Spaces Telemetry クライアントを拡張して、ユーザーのカスタムバックエンドを実装します。
  • カスタムバックエンドの Dev Workspace プラグインを表す plugin.yaml ファイルを作成します。
  • CheCluster カスタムリソースから workspacesDefaultPlugins 属性を設定して、カスタムプラグインの場所を OpenShift Dev Spaces に指定します。
3.6.1.6.1. スタートガイド

以下では、OpenShift Dev Spaces Telemetry システムを拡張してカスタムバックエンドと通信するために必要な手順を説明します。

  1. イベントを受信するサーバープロセスの作成
  2. イベントをサーバーに送信するバックエンドを作成する OpenShift Dev Spaces ライブラリーの拡張
  3. コンテナーでの Telemetry バックエンドのパッケージ化およびイメージレジストリーへのデプロイ
  4. バックエンドのプラグインを追加し、OpenShift Dev Space に Dev Workspaces にプラグインを読み込むよう指示

Telemetry バックエンドの最終的な例については、here を参照してください。

イベントを受信するサーバーの作成

この例は、Telemetry プラグインからイベントを受信し、標準出力に書き込むサーバーを作成する方法を示しています。

実稼働環境のユースケースでは、独自の Telemetry サーバーを作成するのではなく、サードパーティーの Telemetry システム (Segment、Woopra など) との統合を検討してください。この場合、プロバイダーの API を使用してイベントをカスタムバックエンドからシステムに送信します。

以下の Go コードは、ポート 8080 でサーバーを起動し、イベントを標準出力に書き込みます。

例3.12 main.go

package main

import (
	"io/ioutil"
	"net/http"

	"go.uber.org/zap"
)

var logger *zap.SugaredLogger

func event(w http.ResponseWriter, req *http.Request) {
	switch req.Method {
	case "GET":
		logger.Info("GET /event")
	case "POST":
		logger.Info("POST /event")
	}
	body, err := req.GetBody()
	if err != nil {
		logger.With("err", err).Info("error getting body")
		return
	}
	responseBody, err := ioutil.ReadAll(body)
	if err != nil {
		logger.With("error", err).Info("error reading response body")
		return
	}
	logger.With("body", string(responseBody)).Info("got event")
}

func activity(w http.ResponseWriter, req *http.Request) {
	switch req.Method {
	case "GET":
		logger.Info("GET /activity, doing nothing")
	case "POST":
		logger.Info("POST /activity")
		body, err := req.GetBody()
		if err != nil {
			logger.With("error", err).Info("error getting body")
			return
		}
		responseBody, err := ioutil.ReadAll(body)
		if err != nil {
			logger.With("error", err).Info("error reading response body")
			return
		}
		logger.With("body", string(responseBody)).Info("got activity")
	}
}

func main() {

	log, _ := zap.NewProduction()
	logger = log.Sugar()

	http.HandleFunc("/event", event)
	http.HandleFunc("/activity", activity)
	logger.Info("Added Handlers")

	logger.Info("Starting to serve")
	http.ListenAndServe(":8080", nil)
}

このコードに基づいてコンテナーイメージを作成し、これを OpenShift の openshift-devspaces プロジェクトでデプロイメントとして公開します。サンプル Telemetry サーバーのコードは Telemetry-server-example で利用できます。Telemetry サーバーをデプロイするには、リポジトリーのクローンを作成し、コンテナーをビルドします。

$ git clone https://github.com/che-incubator/telemetry-server-example
$ cd telemetry-server-example
$ podman build -t registry/organization/telemetry-server-example:latest .
$ podman push registry/organization/telemetry-server-example:latest

manifest_with_ingress.yaml および manifest_with_route の両方には、Deployment およびサービスの定義が含まれます。また、前者は Kubernetes Ingress も定義しますが、後者は OpenShift Route を定義します。

マニフェストファイルで、プッシュした image に一致する image および host フィールドと、OpenShift クラスターのパブリックホスト名を置き換えます。次に、以下を実行します。

$ kubectl apply -f manifest_with_[ingress|route].yaml -n openshift-devspaces
3.6.1.6.2. バックエンドプロジェクトの作成
注記

開発時に迅速なフィードバックを得るには、Dev Workspace 内で開発を行うことが推奨されます。これにより、クラスターでアプリケーションを実行し、フロントエンドの Telemetry プラグインからイベントを受信できます。

  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/mygroupsrc/test/java/mygroup の下にあるファイルを削除します。
  3. backend-base の最新バージョンおよび Maven コーディネートについては、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. GitHub ユーザー名、個人アクセストークン、che-incubator リポジトリーの詳細を ~/.m2/settings.xml ファイルに追加します。

    例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>
3.6.1.6.3. AnalyticsManager の具体的な実装の作成および特殊なロジックの追加

src/main/java/mygroup の下に、プロジェクトに 2 つのファイルを作成します。

  • MainConfiguration.java - AnalyticsManager に提供される設定が含まれます。
  • AnalyticsManager.java: Telemetry システム固有のロジックが含まれます。

例3.15 MainConfiguration.java

package org.my.group;

import java.util.Optional;

import javax.enterprise.context.Dependent;
import javax.enterprise.inject.Alternative;

import org.eclipse.che.incubator.workspace.telemetry.base.BaseConfiguration;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@Dependent
@Alternative
public class MainConfiguration extends BaseConfiguration {
    @ConfigProperty(name = "welcome.message")      1
    Optional<String> welcomeMessage;               2
}
1
MicroProfile 設定アノテーションは、welcome.message 設定を注入するために使用されます。

バックエンドに固有の設定プロパティーを設定する方法の詳細は、Quarkus 設定リファレンスガイド を参照してください。

例3.16 AnalyticsManager.java

package org.my.group;

import java.util.HashMap;
import java.util.Map;

import javax.enterprise.context.Dependent;
import javax.enterprise.inject.Alternative;
import javax.inject.Inject;

import org.eclipse.che.incubator.workspace.telemetry.base.AbstractAnalyticsManager;
import org.eclipse.che.incubator.workspace.telemetry.base.AnalyticsEvent;
import org.eclipse.che.incubator.workspace.telemetry.finder.DevWorkspaceFinder;
import org.eclipse.che.incubator.workspace.telemetry.finder.UsernameFinder;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.slf4j.Logger;

import static org.slf4j.LoggerFactory.getLogger;

@Dependent
@Alternative
public class AnalyticsManager extends AbstractAnalyticsManager {

    private static final Logger LOG = getLogger(AbstractAnalyticsManager.class);

    public AnalyticsManager(MainConfiguration mainConfiguration, DevWorkspaceFinder devworkspaceFinder, UsernameFinder usernameFinder) {
        super(mainConfiguration, devworkspaceFinder, usernameFinder);

        mainConfiguration.welcomeMessage.ifPresentOrElse(     1
            (str) -> LOG.info("The welcome message is: {}", str),
            () -> LOG.info("No welcome message provided")
        );
    }

    @Override
    public boolean isEnabled() {
        return true;
    }

    @Override
    public void destroy() {}

    @Override
    public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, Map<String, Object> properties) {
        LOG.info("The received event is: {}", event);         2
    }

    @Override
    public void increaseDuration(AnalyticsEvent event, Map<String, Object> properties) { }

    @Override
    public void onActivity() {}
}
1
提供された場合は Welcome メッセージをログに記録します。
2
フロントエンドプラグインから受け取ったイベントをログに記録します。

org.my.group.AnalyticsManagerorg.my.group.MainConfiguration は代替の Bean であるため、src/main/resources/application.propertiesquarkus.arc.selected-alternatives プロパティーを使用して指定します。

例3.17 application.properties

quarkus.arc.selected-alternatives=MainConfiguration,AnalyticsManager
3.6.1.6.4. Dev Workspace 内でのアプリケーションの実行
  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 を使用して Telemetry イベントを受け取るようになりました。

検証手順

  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. AnalyticsManageronEvent() メソッドがフロントエンドプラグインからイベントを受信することを確認するには、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
3.6.1.6.5. isEnabled() の実装

この例では、このメソッドは呼び出されるたびに true を返します。

例3.18 AnalyticsManager.java

@Override
public boolean isEnabled() {
    return true;
}

より複雑なロジックを isEnabled() に設定することができます。たとえば、ホストされている OpenShift Dev Spaces Woopra バックエンド は、バックエンドが有効になっているかどうかを判断する前に、設定プロパティーが存在することを確認します。

3.6.1.6.6. onEvent() の実装

onEvent() は、バックエンドが受信したイベントを Telemetry システムに送信します。サンプルアプリケーションでは、HTTP POST ペイロードを Telemetry サーバーから /event エンドポイントに送信します。

サンプル Telemetry サーバーへの POST 要求の送信

以下の例では、Telemetry サーバーアプリケーションは http://little-telemetry-server-che.apps-crc.testing の URL で OpenShift にデプロイされます。ここで、apps-crc.testing は OpenShift クラスターの Ingress ドメイン名です。

  1. TelemetryService.java を作成して RESTEasy REST Client を設定します。

    例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
    POST リクエストを行うエンドポイント。
  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. TelemetryServiceAnalyticsManager に挿入し、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 要求が Telemetry サーバーに送信され、短期間同じイベントが自動的に遅延します。デフォルトの期間は 1500 ミリ秒です。

3.6.1.6.7. increaseDuration() の実装

多くの Telemetry システムはイベント期間を認識します。AbstractAnalyticsManager は、同じ期間内で発生する同様のイベントを 1 つのイベントにマージします。increaseDuration() のこの実装は no-op です。この方法では、ユーザーの Telemetry プロバイダーの API を使用してイベントまたはイベントプロパティーを変更し、イベントの延長期間を反映します。

例3.22 AnalyticsManager.java

@Override
public void increaseDuration(AnalyticsEvent event, Map<String, Object> properties) {}
3.6.1.6.8. onActivity() の実装

非アクティブなタイムアウトの制限を設定し、最後のイベント時間がタイムアウトよりも長くなる場合は、onActivity() を使用して WORKSPACE_INACTIVE イベントを送信します。

例3.23 AnalyticsManager.java

public class AnalyticsManager extends AbstractAnalyticsManager {

    ...

    private long inactiveTimeLimit = 60000 * 3;

    ...

    @Override
    public void onActivity() {
        if (System.currentTimeMillis() - lastEventTime >= inactiveTimeLimit) {
            onEvent(WORKSPACE_INACTIVE, lastOwnerId, lastIp, lastUserAgent, lastResolution, commonProperties);
        }
    }
3.6.1.6.9. destroy() の実装

destroy() が呼び出される際に、WORKSPACE_STOPPED イベントを送信し、接続プールなどのリソースをシャットダウンします。

例3.24 AnalyticsManager.java

@Override
public void destroy() {
    onEvent(WORKSPACE_STOPPED, lastOwnerId, lastIp, lastUserAgent, lastResolution, commonProperties);
}

「Dev Workspace 内でのアプリケーションの実行」 で説明されているように mvn quarkus:dev を実行し、Ctrl+C でアプリケーションを終了すると、WORKSPACE_STOPPED イベントがサーバーに送信されます。

3.6.1.6.10. Quarkus アプリケーションのパッケージ化

アプリケーションをコンテナーにパッケージ化する最適な方法については、Quarkus ドキュメント を参照してください。コンテナーをビルドし、選択したコンテナーレジストリーにプッシュします。

JVM で実行する Quarkus イメージをビルドするための Dockerfile の例

例3.25 Dockerfile.jvm

FROM registry.access.redhat.com/ubi8/openjdk-11:1.11

ENV LANG='en_US.UTF-8' LANGUAGE='en_US:en'

COPY --chown=185 target/quarkus-app/lib/ /deployments/lib/
COPY --chown=185 target/quarkus-app/*.jar /deployments/
COPY --chown=185 target/quarkus-app/app/ /deployments/app/
COPY --chown=185 target/quarkus-app/quarkus/ /deployments/quarkus/

EXPOSE 8080
USER 185

ENTRYPOINT ["java", "-Dquarkus.http.host=0.0.0.0", "-Djava.util.logging.manager=org.jboss.logmanager.LogManager", "-Dquarkus.http.port=${DEVWORKSPACE_TELEMETRY_BACKEND_PORT}", "-jar", "/deployments/quarkus-run.jar"]

イメージをビルドするには、以下を実行します。

mvn package && \
podman build -f src/main/docker/Dockerfile.jvm -t image:tag .
Quarkus ネイティブイメージをビルドするための Dockerfile の例

例3.26 Dockerfile.native

FROM registry.access.redhat.com/ubi8/ubi-minimal:8.5
WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/application

EXPOSE 8080
USER 1001

CMD ["./application", "-Dquarkus.http.host=0.0.0.0", "-Dquarkus.http.port=$DEVWORKSPACE_TELEMETRY_BACKEND_PORT}"]

イメージをビルドするには、以下を実行します。

mvn package -Pnative -Dquarkus.native.container-build=true && \
podman build -f src/main/docker/Dockerfile.native -t image:tag .
3.6.1.6.11. プラグインの plugin.yaml の作成

DevWorkspacePod でカスタムバックエンドを実行する DevWorkspace プラグインを表す plugin.yamldevfilev2 ファイルを作成します。devfile v2 の詳細については、Devfile v2 documentation を参照してください。

例3.27 plugin.yaml

schemaVersion: 2.1.0
metadata:
  name: devworkspace-telemetry-backend-plugin
  version: 0.0.1
  description: A Demo telemetry backend
  displayName: Devworkspace Telemetry Backend
components:
  - name: devworkspace-telemetry-backend-plugin
    attributes:
      workspaceEnv:
        - name: DEVWORKSPACE_TELEMETRY_BACKEND_PORT
          value: '4167'
    container:
      image: YOUR IMAGE            1
      env:
        - name: WELCOME_MESSAGE    2
          value: 'hello world!'
1
「Quarkus アプリケーションのパッケージ化」 からビルドされたコンテナーイメージを指定します。
2
Example 4 から welcome.message オプションの設定プロパティーの値を設定します。

通常、ユーザーはこのファイルを企業 Web サーバーにデプロイします。本書では、OpenShift で Apache Web サーバーを作成し、そこでプラグインをホストする方法を説明します。

新規 plugin.yaml ファイルを参照する ConfigMap オブジェクトを作成します。

$ oc create configmap --from-file=plugin.yaml -n openshift-devspaces telemetry-plugin-yaml

Web サーバーを公開するためにデプロイメント、サービス、およびルートを作成します。デプロイメントはこの ConfigMap オブジェクトを参照し、これを /var/www/html ディレクトリーに配置します。

例3.28 manifest.yaml

kind: Deployment
apiVersion: apps/v1
metadata:
  name: apache
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apache
  template:
    metadata:
      labels:
        app: apache
    spec:
      volumes:
        - name: plugin-yaml
          configMap:
            name: telemetry-plugin-yaml
            defaultMode: 420
      containers:
        - name: apache
          image: 'registry.redhat.io/rhscl/httpd-24-rhel7:latest'
          ports:
            - containerPort: 8080
              protocol: TCP
          resources: {}
          volumeMounts:
            - name: plugin-yaml
              mountPath: /var/www/html
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 25%
      maxSurge: 25%
  revisionHistoryLimit: 10
  progressDeadlineSeconds: 600
---
kind: Service
apiVersion: v1
metadata:
  name: apache
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  selector:
    app: apache
  type: ClusterIP
---
kind: Route
apiVersion: route.openshift.io/v1
metadata:
  name: apache
spec:
  host: apache-che.apps-crc.testing
  to:
    kind: Service
    name: apache
    weight: 100
  port:
    targetPort: 8080
  wildcardPolicy: None
$ oc apply -f manifest.yaml

検証手順

  • デプロイメントが開始されたら、Web サーバーで plugin.yaml が利用できることを確認します。

    $ curl apache-che.apps-crc.testing/plugin.yaml
3.6.1.6.12. Dev Workspace での Telemetry プラグインの指定
  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. Telemetry-plug-in コンテナーが Dev Workspace Pod で稼働していることを確認します。ここでは、これはエディターで Workspace ビューをチェックして検証されます。

    Dev Workspace Telemetry プラグイン
  2. エディター内のファイルを編集し、Telemetry サーバーのログのサンプルでイベントを確認します。
3.6.1.6.13. すべての Dev Workspaces の Telemetry プラグインの適用

Telemetry プラグインをデフォルトのプラグインとして設定します。デフォルトのプラグインは、新規および既存の Dev Workspaces の Dev Workspace の起動に適用されます。

  • CheCluster カスタムリソースを設定します。「CLI を使用して CheCluster カスタムリソースの設定」を参照してください。

    spec:
      devEnvironments:
        defaultPlugins:
        - editor: eclipse/che-theia/next     1
          plugins:                           2
          - 'http://apache-che.apps-crc.testing/plugin.yaml'
    1
    デフォルトのプラグインを設定するエディターの ID。
    2
    devfile v2 プラグインへの URL の一覧。

検証手順

  1. Red Hat OpenShift Dev Spaces ダッシュボードから新規または既存の Dev Workspace を起動します。
  2. 「Dev Workspace での Telemetry プラグインの指定」 の検証手順に従って、Telemetry プラグインが機能していることを確認します。

3.6.2. サーバーロギングの設定

OpenShift Dev Spaces サーバーで利用可能な個別のロガーのログレベルを微調整できます。

OpenShift Dev Spaces サーバー全体のログレベルは、Operator の cheLogLevel 設定プロパティーを使用してグローバルに設定されます。CheCluster カスタムリソースフィールドの参照」を参照してください。Operator によって管理されないインストールでグローバルログレベルを設定するには、che ConfigMap で CHE_LOG_LEVEL 環境変数を指定します。

CHE_LOGGER_CONFIG 環境変数を使用して、OpenShift Dev Spaces サーバーの個々のロガーのログレベルを設定することができます。

3.6.2.1. ログレベルの設定

手順

  • CheCluster カスタムリソースを設定します。「CLI を使用して CheCluster カスタムリソースの設定」を参照してください。

    spec:
      components:
        cheServer:
          extraProperties:
            CHE_LOGGER_CONFIG: "<key1=value1,key2=value2>" 1
    1
    キーと値のペアのコンマ区切りリスト。キーは OpenShift Dev Spaces サーバーログ出力に表示されるロガーの名前で、値は必要なログレベルになります。

    例3.29 WorkspaceManager のデバッグモードの設定

    spec:
      components:
        cheServer:
          extraProperties:
            CHE_LOGGER_CONFIG: "org.eclipse.che.api.workspace.server.WorkspaceManager=DEBUG"

3.6.2.2. ロガーの命名

ロガーの名前は、それらのロガーを使用する内部サーバークラスのクラス名に従います。

3.6.2.3. HTTP トラフィックのロギング

手順

  • OpenShift Dev Spaces サーバーと Kubernetes または OpenShift クラスターの API サーバー間の HTTP トラフィックをログに記録するには、CheCluster カスタムリソースを設定します。「CLI を使用して CheCluster カスタムリソースの設定」を参照してください。

    spec:
      components:
        cheServer:
          extraProperties:
            CHE_LOGGER_CONFIG: "che.infra.request-logging=TRACE"

3.6.3. dsc を使用したログの収集

Red Hat OpenShift Dev Spaces のインストールは、OpenShift クラスターで実行されている複数のコンテナーで設定されます。実行中の各コンテナーからログを手動で収集できますが、dsc はプロセスを自動化するコマンドを提供します。

以下のコマンドを使用すると、dsc ツールを使用して OpenShift クラスターから Red Hat OpenShift Dev Spaces ログを収集します。

dsc server:logs

既存の Red Hat OpenShift Dev Spaces サーバーログを収集し、ローカルマシンのディレクトリーに保存します。デフォルトでは、ログはマシンの一時ディレクトリーにダウンロードされます。ただし、-d パラメーターを指定すると上書きできます。たとえば、OpenShift Dev Spaces:wq:q ログを /home/user/che-logs/ ディレクトリーにダウンロードするには、次のコマンドを使用します。

dsc server:logs -d /home/user/che-logs/

実行すると、dsc server:logs はログファイルを保存するディレクトリーを指定するコンソールにメッセージを出力します。

Red Hat OpenShift Dev Spaces logs will be available in '/tmp/chectl-logs/1648575098344'

Red Hat OpenShift Dev Spaces がデフォルト以外のプロジェクトにインストールされている場合、dsc server:logs には -n <NAMESPACE> パラメーターが必要です。ここで、<NAMESPACE> は Red Hat OpenShift Dev Spaces がインストールされた OpenShift プロジェクトです。たとえば、my-namespace プロジェクトの OpenShift Dev Spaces からログを取得するには、以下のコマンドを使用します。

dsc server:logs -n my-namespace
dsc server:deploy
ログは、dsc を使用してインストール時に OpenShift Dev Spaces のインストール時に自動的に収集されます。dsc server:logs と同様に、ディレクトリーのログは -d パラメーターを使用して指定できます。

3.6.4. Prometheus および Grafana のモニタリング

クラスター上で実行中の Prometheus および Grafana のインスタンスを使用して、OpenShift Dev Spaces メトリクスを収集および表示できます。

3.6.4.1. Prometheus と Grafana のインストール

template.yaml を適用して Prometheus および Grafana をインストールできます。この例の template.yaml ファイルは、Prometheus および Grafana を使い始めるための基本的な設定、Deployments および Services のモニタリングスタックを提供します。

または、Prometheus OperatorGrafana Operator を使用することもできます。

前提条件

  • oc

手順

template.yaml を使用して Prometheus と Grafana をインストールするには、以下を実行します。

  1. Prometheus および Grafana の新規プロジェクト monitoring を作成します。

    $ oc new-project monitoring
  2. monitoring プロジェクトで template.yaml を適用します。

    $ oc apply -f template.yaml -n monitoring

例3.30 template.yaml

---
apiVersion: v1
kind: Service
metadata:
  name: grafana
  labels:
    app: grafana
spec:
  ports:
  - name: 3000-tcp
    port: 3000
    protocol: TCP
    targetPort: 3000
  selector:
    app: grafana
---
apiVersion: v1
kind: Service
metadata:
  name: prometheus
  labels:
    app: prometheus
spec:
  ports:
  - name: 9090-tcp
    port: 9090
    protocol: TCP
    targetPort: 9090
  selector:
    app: prometheus
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: grafana
  name: grafana
spec:
  selector:
    matchLabels:
      app: grafana
  template:
    metadata:
      labels:
        app: grafana
    spec:
      containers:
      - image: registry.redhat.io/rhel8/grafana:7
        name: grafana
        ports:
        - containerPort: 3000
          protocol: TCP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: prometheus
  name: prometheus
spec:
  selector:
    matchLabels:
      app: prometheus
  template:
    metadata:
      labels:
        app: prometheus
    spec:
      serviceAccountName: prometheus
      containers:
      - image: quay.io/prometheus/prometheus:v2.36.0
        name: prometheus
        ports:
        - containerPort: 9090
          protocol: TCP
        volumeMounts:
        - mountPath: /prometheus
          name: volume-data
        - mountPath: /etc/prometheus/prometheus.yml
          name: volume-config
          subPath: prometheus.yml
      volumes:
      - emptyDir: {}
        name: volume-data
      - configMap:
          defaultMode: 420
          name: prometheus-config
        name: volume-config
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
data:
  prometheus.yml: ""
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: prometheus
---

3.6.4.2. Dev Workspace Operator のモニターリング

Dev Workspace Operator が公開するメトリクスを処理するために、モニターリングスタックの例を設定できます。

3.6.4.2.1. Prometheus による Dev Workspace Operator メトリクスの収集

Prometheus を使用して、Dev Workspace Operator に関するメトリクスを収集、保存、および照会するには、以下を実行します。

前提条件

  • devworkspace-controller-metrics サービスは、ポート 8443 でメトリクスを公開している。これはデフォルトで事前設定されています。
  • devworkspace-webhookserver サービスは、ポート 9443 でメトリクスを公開している。これはデフォルトで事前設定されています。
  • Prometheus 2.26.0 以降が動作している。Prometheus コンソールは、ポート 9090 で実行されており、対応するサービスがあります。Prometheus を初めて実行するための手順 について参照してください。

手順

  1. ClusterRoleBinding を作成して、Prometheus に関連付けられた ServiceAccount を devworkspace-controller-metrics-reader ClusterRole にバインドします。監視スタックの例 では、使用される ServiceAccount の名前は prometheus です。

    注記

    Dev Workspace メトリクスへのアクセスはロールベースアクセスコントロール (RBAC) で保護されているため、ClusterRoleBinding がないとアクセスできません。

    例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 サービスが公開するポート 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 が監視するリソースデフォルトの設定では、2 つのジョブ (DevWorkspace および DevWorkspace webhooks) が、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 サービスにアクセスします。

    $ oc port-forward svc/prometheus 9090:9090 -n monitoring
  2. localhost:9090/targets でターゲットエンドポイントを表示して、すべてのターゲットが稼働していることを確認します。
  3. Prometheus コンソールを使用して、メトリクスを表示および照会します。

    • localhost:9090/metrics でメトリクスを表示します。
    • localhost:9090/graph からメトリクスをクエリーします。

      詳細は、Using the expression browser を参照してください。

3.6.4.2.2. Dev Workspace 固有のメトリクス

次の表は、devworkspace-controller-metrics サービスによって公開される Dev Workspace 固有のメトリックについて説明しています。

表3.20 メトリック
名前説明ラベル

devworkspace_started_total

カウンター

Dev Workspace の開始イベントの数。

sourceroutingclass

devworkspace_started_success_total

カウンター

Running 段階に移行した Dev Workspaces の数。

sourceroutingclass

devworkspace_fail_total

カウンター

失敗した Dev Workspaces の数。

sourcereason

devworkspace_startup_time

ヒストグラム

Dev Workspace の起動にかかった総時間 (秒)。

sourceroutingclass

表3.21 ラベル
名前説明

source

Dev Workspace の controller.devfile.io/devworkspace-source ラベルです。

string

routingclass

Dev Workspace の spec.routingclass です。

"basic|cluster|cluster-tls|web-terminal"

reason

ワークスペースの起動失敗の理由です。

"BadRequest|InfrastructureFailure|Unknown"

表3.22 スタートアップ失敗の理由
名前説明

BadRequest

Dev Workspace の作成に使用された devfile が無効であるため、起動に失敗しました。

InfrastructureFailure

CreateContainerErrorRunContainerErrorFailedSchedulingFailedMount のエラーによる起動の失敗。

Unknown

不明な失敗理由。

3.6.4.2.3. Grafana ダッシュボードでの Dev Workspace Operator メトリクスの表示

ダッシュボードの例を使用して Grafana の Dev Workspace Operator メトリクスを表示するには、以下を実行します。

前提条件

手順

  1. Prometheus インスタンスのデータソースを追加します。Creating a Prometheus data source を参照してください。
  2. example grafana-dashboard.json ダッシュボードをインポートします。

検証手順

3.6.4.2.4. Dev Workspace Operator の Grafana ダッシュボード

grafana-dashboard.json に基づく サンプルの Grafana ダッシュボードには、Dev Workspace Operator から次のメトリクスが表示されます。

Dev Workspace-specific metrics パネル

図3.1 Dev Workspace-specific metrics パネル

`DevWorkspace の起動に関連するメトリクスを含む Grafana ダッシュボードパネル
ワークスペースの平均起動時間
ワークスペースの平均起動時間。
ワークスペースの起動
ワークスペースの起動の成功と失敗の回数。
ワークスペースの起動時間
ワークスペースの起動時間を表示するヒートマップ。
Dev Workspace の成功/失敗
DevWorkspace の起動の成功と失敗の比較。
Dev Workspace の失敗率
ワークスペースの起動失敗回数と総起動回数の比率。
Dev Workspace 起動失敗の理由

ワークスペース起動失敗の分布を表示する円グラフ:

  • BadRequest
  • InfrastructureFailure
  • Unknown
Operator metrics パネル (パート 1)

図3.2 Operator metrics パネル (パート 1)

Operator メトリクスパート 1 を含む Grafana ダッシュボードパネル
進行中の Webhook
さまざまな Webhook リクエストの数の比較。
作業キューの期間
調整リクエストが処理される前にワークキューにとどまる時間を表示するヒートマップ。
Webhook のレイテンシー (/mutate)
/mutate Webhook レイテンシーを表示するヒートマップ。
調整時間
調整期間を表示するヒートマップ。
Operator metrics パネル (パート 2)

図3.3 Operator metrics パネル (パート 2)

Operator メトリクスパート 2 を含む Grafana ダッシュボードパネル
Webhook のレイテンシー (/convert)
/convert Webhook レイテンシーを表示するヒートマップ。
作業キューの深さ
作業キューにある調整リクエストの数。
メモリー
Dev Workspace コントローラーと Dev Workspace Webhook サーバーのメモリー使用状況。
調整数 (DWO)
Dev Workspace コントローラーの 1 秒あたりの平均調整回数。

3.6.4.3. Dev Spaces サーバーの監視

OpenShift Dev Spaces サーバーの JVM メモリーやクラ出力ディングなどの JVM メトリクスを公開するように OpenShift Dev Spaces を設定できます。

3.6.4.3.1. OpenShift Dev Spaces サーバーメトリクスの有効化と公開

OpenShift Dev Spaces は、che-host サービスのポート 8087 で JVM メトリクスを公開します。この動作を設定できます。

手順

3.6.4.3.2. Prometheus を使用した OpenShift Dev Spaces メトリクスの収集

Prometheus を使用して、OpenShift Dev Spaces サーバーの JVM メトリクスを収集、保存、および照会するには、以下を実行します。

前提条件

手順

  1. ポート 8087 からメトリクスを収集するように Prometheus を設定します。

    注記

    モニターリングスタックのサンプル では、空の設定で 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: 'Che Server'
              static_configs:
                - targets: ['che-host.<OpenShift Dev Spaces_project>:8087']  4
    1
    ターゲットが収集されるレート。
    2
    記録およびアラートルールを再チェックするレート。
    3
    Prometheus が監視するリソースデフォルト設定では、単一のジョブ Che Server が、OpenShift Dev Spaces Server によって公開された時系列データをスクレイピングします。
    4
    ポート 8087 からのメトリクスのスクレイプターゲット。<OpenShift Dev Spaces_project> を 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 サービスにアクセスします。

    $ oc port-forward svc/prometheus 9090:9090 -n monitoring
  2. localhost:9090/targetstargets エンドポイントを表示して、すべてのターゲットが稼働していることを確認します。
  3. Prometheus コンソールを使用して、メトリクスを表示および照会します。

    • localhost:9090/metrics でメトリクスを表示します。
    • localhost:9090/graph からメトリクスをクエリーします。

      詳細は、Using the expression browser を参照してください。

3.6.4.3.3. Grafana ダッシュボードでの OpenShift Dev Spaces サーバーメトリクスの表示

Grafana で OpenShift Dev Spaces サーバーメトリクスを表示するには、以下を実行します。

前提条件

手順

  1. Prometheus インスタンスのデータソースを追加します。Creating a Prometheus data source を参照してください。
  2. サンプル ダッシュボード をインポートします。Import dashboard を参照してください。
  3. Grafana コンソールで OpenShift Dev Spaces メトリクスを表示します。

    図3.4 OpenShift Dev Spaces サーバーの JVM ダッシュボード

    *OpenShift Dev Spaces サーバー の JVM* ダッシュボード

    図3.5 クイックファクト

    *JVM クイックファクト* パネル

    図3.6 JVM メモリー

    *JVM メモリー* パネル

    図3.7 JVM Misc

    *JVM その他* パネル

    図3.8 JVM メモリープール (ヒープ)

    *JVM メモリープール (ヒープ)* パネル

    図3.9 JVM メモリープール (非ヒープ)

    *JVM メモリープール (非ヒープ)* パネル

    図3.10 ガベージコレクション

    *JVM ガベージコレクション* パネル

    図3.11 クラ出力ディング

    *JVM クラスのローディング* パネル

    図3.12 バッファープール

    *JVM バッファープール* パネル
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.