# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

public_url: "https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent/third-party/jvm"
app_url: "https://docs.oracle.com/javase/specs/index.html"
short_name: JVM
long_name: JVM
logo_path: /stackdriver/images/java.png # supplied by google technical writer
description: |-
  The JVM integration collects JVM metrics exposed through [Java Management
  Extensions (JMX)](https://www.oracle.com/java/technologies/javase/javamanagement.html).
  The integration primarily collects metrics on memory and garbage collection.
  Additional runtime metrics, such as thread count and classes loaded, are also
  available.
configure_integration: |-
  To expose a JMX endpoint, you must set the `com.sun.management.jmxremote.port`
  system property when starting the JVM. We also recommend setting the
  `com.sun.management.jmxremote.rmi.port` system property to the same port.

  To expose a JMX endpoint remotely, you must also set the
  `java.rmi.server.hostname` system property.

  To set system properties by using command-line arguments, prepend the property
  name with `-D` when starting the JVM.

  For example, to set `com.sun.management.jmxremote.port` to port `9999`, specify
  the following when starting the JVM:

  <pre>
  -Dcom.sun.management.jmxremote.port=9999
  </pre>
minimum_supported_agent_version:
  metrics: 2.2.0
supported_operating_systems: linux
supported_app_version: ["Java 16", "Java 11"]
expected_metrics:
  - type: workload.googleapis.com/jvm.classes.loaded
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.gc.collections.count
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: name
        value_regex: .*
  - type: workload.googleapis.com/jvm.gc.collections.elapsed
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: name
        value_regex: .*
  - type: workload.googleapis.com/jvm.memory.heap.committed
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.heap.init
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.heap.max
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.heap.used
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    representative: true
  - type: workload.googleapis.com/jvm.memory.nonheap.committed
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.nonheap.init
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.nonheap.max
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.nonheap.used
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/jvm.memory.pool.committed
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: name
        value_regex: .*
  - type: workload.googleapis.com/jvm.memory.pool.init
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: name
        value_regex: .*
  - type: workload.googleapis.com/jvm.memory.pool.max
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: name
        value_regex: .*
  - type: workload.googleapis.com/jvm.memory.pool.used
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: name
        value_regex: .*
  - type: workload.googleapis.com/jvm.threads.count
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
configuration_options:
  metrics:
    - type: jvm
      fields:
        - name: type
          default: null
          description: This value must be `jvm`.
        - name: endpoint
          default: localhost:9999
          description: The [JMX Service URL](https://docs.oracle.com/javase/8/docs/api/javax/management/remote/JMXServiceURL.html) or host and port used to construct the service URL. This value must be in the form of `service:jmx:<protocol>:<sap>` or `host:port`. Values in `host:port` form are used to create a service URL of `service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi`.
        - name: username
          default: null
          description: The configured username if JMX is configured to require authentication.
        - name: password
          default: null
          description: The configured password if JMX is configured to require authentication.
        - name: collection_interval
          default: 60s
          description: A [time duration](https://pkg.go.dev/time#ParseDuration) value, such as `30s` or `5m`.
