---
title: 'Debugging: Where to Look First | Shopware Community Hub'
description: >-
Learn how to approach debugging on Native PaaS by identifying the problem type
first, choosing the right observability tool, and interpreting signals from
the…
canonical_url: 'https://hub.shopware.com/learn/unit/debugging-where-to-look-first'
---
# Debugging: Where to Look First
- Distinguish deployment, runtime, request-level, and service-related problems as different debugging starting points.
- Choose the right debugging tool for the situation, including Grafana, `sw-paas watch`, and `sw-paas open admin`.
- Interpret what different log sources such as Shopware, workers, and the database can tell you.
- Recognize when platform boundaries, known issues, or retention limits affect the debugging process.
# Debugging: Where to Look First
When something breaks on Native PaaS, the first challenge is usually not reading logs. It is deciding **where** to look first.
Some problems happen during deployment. Others appear only after the application is already live. Some belong to Shopware itself, while others come from workers, the database, or surrounding services.
In this learning unit, you learn how to use the available observability tools without turning debugging into guesswork.
The goal is simple: Identify the likely problem area first, then open the tool that gives you the most useful signal.
## Start With the Right Debugging Question
Before opening Grafana or reading raw logs, ask one question: **What kind of problem am I looking at?**
In practice, most issues fall into one of these buckets:
| Situation | Look here first | Why |
|-------------------------------------|---------------------------------------------------|----------------------------------------------|
| Deployment running or just failed | `sw-paas watch` and deploy logs | First locate the active or failed phase. |
| Deploy finished, shop behaves badly | Grafana and application logs | This points more to runtime than rollout. |
| Request is slow or failing | Grafana Explore, logs, and traces where available | You need request-level runtime signals. |
| Service-related symptom | The log source for that layer | The signal may come from a different layer. |
This is the core debugging model for Native PaaS: Always place the problem first, then choose the tool.
At this stage, you do not need a full diagnosis. You only need a useful first direction.
Once you have that, debugging becomes much easier because you stop treating every issue as a generic log problem.
## Observability on Native PaaS
Once you have identified the type of problem, the next step is to open the tool that gives you the right signal.
On Native PaaS, you work with a managed setup where each tool has a clear role.
The most important rule is this:
- Use **Grafana** as the main entry point for investigation.
- Use **Loki** for log streams.
- Use deployment monitoring when the question is still about rollout state.
In practice, this means:
- If the issue is about **runtime behavior**, start in Grafana.
- If the issue is about **deployment state**, stay with `sw-paas watch` and deploy logs.
### Working Inside Grafana
Grafana is your central place for investigation.
- Use **Explore -> Loki** to search and filter logs.
- Use labels such as `component` when available to narrow results.
- Start with predefined dashboards (for example Logs dashboards) when you want a quick overview instead of building queries manually.
If tracing is available in your environment:
- Use **Tempo** with query type **Search**.
- Filter by services such as `shopware` when investigating slow or failing requests.
### Retention and Practical Limits
Log and trace retention is **finite**.
- **Loki** logs are typically retained for around **45 days**.
- **Tempo** traces are typically retained for around **14 days**.
Treat these values as orientation. If your team needs longer history for compliance or audits, export logs early instead of assuming they will remain available indefinitely.
## Open the Right Tool
Once you know what you are trying to inspect, the next step is to choose the matching access pattern.
In practice, these three tools answer different questions:
- **Is this a runtime problem?** Start with Grafana.
- **Is the rollout itself still the problem?** Stay with `sw-paas watch` and deploy logs.
- **Do I need to verify the live Shopware state directly?** Use `sw-paas open admin`.
### Open Grafana
Start with Grafana when the application is already running and you need runtime signals, log exploration, or dashboard-based troubleshooting.
```bash
sw-paas open grafana
```
Select the correct organization, project, and application when prompted. This matters because dashboards and logs are tied to one application context.
### Watch Deployment Events
Use `watch` when the rollout itself is still the question.
```bash
sw-paas watch
```
This is the fastest way to see whether deployment activity is still progressing or whether it already failed in a specific phase.
When the live stream is already over and you need targeted deployment history, use `sw-paas application deploy get` or the corresponding UI views to inspect a specific deployment afterwards.
### Verifying the Application State in the Shopware Administration
The `sw-paas open ...` commands are CLI helpers that open platform-related targets for the selected application.
`sw-paas open admin` opens the Shopware administration for that application. It is not a log tool, but it is useful during debugging when you want to compare log signals with the actual live application state.
```bash
sw-paas open admin
```
This pattern avoids copy/paste mistakes for admin credentials resolved through Vault and gives you a quick way to verify what the shop is actually doing.
Use this when logs alone do not tell you enough.
For example:
- Does the error from the logs also appear in the UI?
- Did the deployment actually change the expected data or configuration?
- Is a feature behaving incorrectly even though the logs look normal?
A simple rule helps here:
Logs tell you what happened.
The Shopware administration shows you how the application actually behaves.
Together, they help you avoid false conclusions from log output alone.
## Know Which Log Source You Are Reading
Not every failure shows up in the same place, and not every log line points to the same layer.
Before diving deeper, identify which part of the system you are actually looking at.
Use this mental map:
| Source | Typical signals | What it often points to |
|-----------------|-----------------------------------------------------------|----------------------------------------------------------------------|
| PHP / Shopware | Exceptions, 500 errors, plugin fatals | Application logic, plugin code, or request handling inside Shopware |
| Workers / queue | Failed messages, retries, stuck background jobs | Problems in asynchronous processing or queue consumers |
| Database | Slow queries, locks, unstable data access | Performance bottlenecks or data-layer issues |
This helps you place the problem in the right context more quickly.
## Typical Debugging Boundaries
Not every problem comes from your application.
Some issues come from platform boundaries, environment behavior, or known limitations instead.
This matters when the symptom looks like a normal Shopware or plugin problem at first, but the real cause sits somewhere else.
Keep the official [Known Issues](https://developer.shopware.com/docs/products/paas/shopware/known-issues.html) page nearby when the usual application-level explanation does not fully fit.
Relevant examples include:
- Message queue size limits that affect how background jobs behave.
- S3 compatibility expectations that can break plugins relying on unsupported storage assumptions.
These cases are especially tricky because they often look like normal application problems at first.
Datadog, New Relic, and similar tools are not part of the same managed path by default.
If a project requires them, treat that as an additional integration decision rather than as the default observability model on Native PaaS.
## Use UI or CLI Depending on Context
The CLI is not the only way to inspect runtime information. Many platform views also exist in the web UI.
Current enablement often frames this as rough UI parity for many day-to-day workflows such as organization, project, and application navigation as well as build and deploy log access.
Use the CLI when you want to work step by step in a direct terminal workflow, repeat the same checks later, or share exact commands with teammates.
Use the UI when browser access is faster for handover, quick inspection, or navigation across organizations, projects, and applications.
Both use the same underlying platform. Choose the interface that best fits the situation.
## Check your understanding
A production deployment failed 10 minutes ago, and the team is not sure whether the application ever reached the new version. Where should you start?
Open Grafana first and search PHP logs, because every production issue is a runtime issue
Use `sw-paas watch`, deploy logs, or deployment history to find the failing rollout stage before investigating runtime symptoms
Open the Shopware administration and clear caches, because rollout state is best verified there
Orders are accepted normally, but confirmation emails are delayed. The last deployment finished successfully. Which signal should you inspect first?
The domain DNS records, because delayed emails usually mean the custom domain is not verified
Worker or queue-related logs in Grafana/Loki, because the symptom points to asynchronous processing rather than rollout state
`sw-paas open admin` only, because the administration replaces log inspection for queue issues
## Summary
In this learning unit, you learned:
- How to start debugging by identifying the likely problem type before opening tools.
- How Grafana, Loki, `sw-paas watch`, and `sw-paas open admin` support different debugging questions.
- How to read log and observability signals in the right layer, from Shopware to workers and the database.
- Why known platform boundaries and finite retention can change how you investigate a problem.
With this understanding, you can approach debugging on Native PaaS more systematically, choose the right signal earlier, and avoid wasting time in the wrong tool or layer.