:_mod-docs-content-type: ASSEMBLY
[id="virt-troubleshooting"]
= Troubleshooting
include::_attributes/common-attributes.adoc[]
:context: virt-troubleshooting
:toclevels: 4

{VirtProductName} provides tools and logs for troubleshooting virtual machines (VMs) and virtualization components.

toc::[]

You can troubleshoot {VirtProductName} components by using the tools provided in the web console or by using the `oc` CLI tool.

// This section is in an assembly so that we can use xrefs.
[id="events_{context}"]
== Events

xref:../../nodes/clusters/nodes-containers-events.adoc#nodes-containers-events[{product-title} events] are records of important life-cycle information and are useful for monitoring and troubleshooting virtual machine, namespace, and resource issues.

* VM events: Navigate to the *Events* tab of the *VirtualMachine details* page in the web console.

Namespace events::
You can view namespace events by running the following command:
+
[source,terminal]
----
$ oc get events -n <namespace>
----
+
See the xref:../../nodes/clusters/nodes-containers-events.adoc#nodes-containers-events-list_nodes-containers-events[list of events] for details about specific events.

Resource events::
You can view resource events by running the following command:
+
[source,terminal]
----
$ oc describe <resource> <resource_name>
----

[id="virt-pod-logs_{context}"]
== Pod logs

You can view logs for {VirtProductName} pods by using the web console or the CLI. You can also view xref:../../virt/support/virt-troubleshooting.adoc#virt-viewing-logs-loki_virt-troubleshooting[aggregated logs] by using the LokiStack in the web console.

include::modules/virt-configuring-pod-log-verbosity.adoc[leveloffset=+2]

include::modules/virt-viewing-virt-launcher-pod-logs-web.adoc[leveloffset=+2]

include::modules/virt-viewing-logs-cli.adoc[leveloffset=+2]

[id="guest-system-logs_{context}"]
== Guest system logs

Viewing the boot logs of VM guests can help diagnose issues. You can configure access to guests' logs and view them by using either the {product-title} web console or the {oc-first}.

Even if the guest VM has no network, you can access it using its VNC or serial console, as documented in xref:../../virt/managing_vms/virt-accessing-vm-consoles.adoc#virt-accessing-vm-consoles[Connecting to virtual machine consoles]

This feature is disabled by default. If a VM does not explicitly have this setting enabled or disabled, it inherits the cluster-wide default setting.

[IMPORTANT]
====
If sensitive information such as credentials or other personally identifiable information (PII) is written to the serial console, it is logged with all other visible text. Red Hat recommends using SSH to send sensitive data instead of the serial console.
====

include::modules/virt-enable-guest-log-default-web.adoc[leveloffset=+2]

include::modules/virt-enable-guest-log-default-cli.adoc[leveloffset=+2]

include::modules/virt-set-guest-log-single-vm-web.adoc[leveloffset=+2]

include::modules/virt-set-guest-log-single-vm-cli.adoc[leveloffset=+2]

include::modules/virt-view-guest-system-logs-web.adoc[leveloffset=+2]

include::modules/virt-view-guest-system-logs-cli.adoc[leveloffset=+2]

[id="log-aggregation_{context}"]
== Log aggregation

You can facilitate troubleshooting by aggregating and filtering logs.

include::modules/virt-viewing-logs-loki.adoc[leveloffset=+2]

include::modules/virt-loki-log-queries.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources for LokiStack and LogQL
//* xref :../../observability/logging/log_storage/about-log-storage.adoc#about-log-storage[About log storage]
//* xref :../../observability/logging/log_storage/installing-log-storage.adoc#cluster-logging-loki-deploy_installing-log-storage[Deploying the LokiStack]
* link:https://grafana.com/docs/loki/latest/logql/log_queries/[LogQL log queries] in the Grafana documentation

include::modules/virt-common-error-messages.adoc[leveloffset=+1]

[id="troubleshooting-data-volumes_{context}"]
== Troubleshooting data volumes

You can check the `Conditions` and `Events` sections of the `DataVolume` object to analyze and resolve issues.

include::modules/virt-about-dv-conditions-and-events.adoc[leveloffset=+2]

include::modules/virt-analyzing-datavolume-conditions-and-events.adoc[leveloffset=+2]
