WebSphereLibertyTrace custom resource

The WebSphereLibertyTrace custom resource (CR) provides server traces of a Liberty server instance that is running in a pod.

WebSphereLibertyTrace prerequisites

The Liberty server must allow configuration drop-ins. The following configuration must not be set on the server. Otherwise, a WebSphereLibertyTrace operation does not work on the server.

<config updateTrigger="disabled"/>

Before you can use WebSphereLibertyTrace, the WebSphereLibertyApplication CR must configure storage for serviceability and a CR for WebSphereLibertyTrace must exist in the same namespace as the WebSphereLibertyApplication CR.

WebSphereLibertyTrace provides a day-2 operation. For automatic discovery of supported day-2 operations from external tools, the following annotations must exist in the WebSphereLibertyApplication and WebSphereLibertyTrace custom resource definitions (CRDs).

The WebSphereLibertyApplication CRD must have an annotation that specifies the WebSphereLibertyTrace day-2 operation. The following example adds annotations for both day-2 operations.
```
annotations:
  openliberty.io/day2operations: WebSphereLibertyTrace,WebSphereLibertyDump
```
The WebSphereLibertyTrace CRD must have an annotation that specifies the Pod k8s Kind for the day-2 operation.
```
annotations:
  day2operation.openliberty.io/targetKinds: Pod
```

WebSphereLibertyTrace configurable parameters

The WebSphereLibertyTrace CRD has configurable parameters. The following list describes the parameters.

Tip: You can refer to child parameters with the parent_parameter.child_parameter format. For example, license.accept.

disable

A Boolean toggle to disable or enable tracing. Set to true to stop tracing.

license

(Required) Information about the license, which is available at https://ibm.biz/was-license.

accept: A Boolean that specifies whether the license is accepted. The default is false. The value must be true to accept the license and enable deployment of the WebSphereLibertyTrace day-2 operation.

maxFiles

If an enforced maximum file size exists, the maximum number of each log file to keep. This parameter also applies to the number of exception logs that summarize exceptions that occur on a day.

maxFileSize

The maximum size (in MB) that a log file can reach before rollover. To disable this attribute, set the value to 0. The default value is 20.

podName

(Required) The name of the Pod, which must be in the same namespace as the WebSphereLibertyTrace CR.

traceSpecification

(Required) The trace string to use to selectively enable trace. The default is the *=info value.

WebSphereLibertyTrace example

The following YAML example sets values for license, podName, traceSpecification, maxFileSize, maxFiles, and disable parameters in the WebSphereLibertyTrace CR.

apiVersion: liberty.websphere.ibm.com/v1
kind: WebSphereLibertyTrace
metadata:
  name: example-trace
spec:
  license:
    accept: false
  podName: my_pod_name
  traceSpecification: "*=info:com.ibm.ws.webcontainer*=all"
  maxFileSize: 20
  maxFiles: 5
  disable: false

Generated trace files, along with messages.log files, are stored in the serviceability folder with a format such as /serviceability/namespace/pod_name/timestamp.zip.

After a trace starts, you can stop it by setting the disable parameter to true. Deleting the CR also stops the tracing. Changing the podName first stops the tracing on the old pod before it enables traces on the new pod.

You can check the status of a trace operation in the status field of the CR YAML. You can also run an Red Hat® OpenShift® CLI (oc) or Kubernetes CLI (kubectl) get wltrace command to see the status of all trace operations in the current namespace.

oc get wltrace -o wide

kubectl get wltrace -o wide

wltrace and wltraces are short names for webspherelibertytrace, the singular name, and webspherelibertytraces, the plural name.

The operator does not monitor the pods. If the pod is restarted or deleted after the trace is enabled, then the tracing is not automatically enabled when the pod restarts. In that situation, the status of the trace operation might not correctly report whether the trace is enabled.