|
| 1 | +import { InlineIcon } from "docs-ui" |
| 2 | +import { ArrowDownTray, ArrowPath, Brackets } from "@medusajs/icons" |
| 3 | + |
| 4 | +export const metadata = { |
| 5 | + title: `Logs`, |
| 6 | +} |
| 7 | + |
| 8 | +# {metadata.title} |
| 9 | + |
| 10 | +In this guide, you'll learn how to view and manage your environment's logs in Cloud. |
| 11 | + |
| 12 | +## Logs Overview |
| 13 | + |
| 14 | +Logs are output messages from your Medusa application's build and runtime processes for an environment's deployments. |
| 15 | + |
| 16 | +They include messages logged throughout your application's lifecycle, including messages during the build process, application startup, and runtime operations. |
| 17 | + |
| 18 | +Logs are essential for monitoring your application's health and debugging issues that may arise during development, deployment, or when the application is running in production. |
| 19 | + |
| 20 | +### Log Types |
| 21 | + |
| 22 | +There are two types of logs for your environment's deployments: |
| 23 | + |
| 24 | +- **Build logs**: Messages generated during the build process before deploying and starting the application. These logs are useful for debugging when a deployment's build fails. |
| 25 | +- **Runtime logs**: Messages logged by the Medusa application when it starts and while it's running, such as informational startup messages, HTTP requests, errors, and more. These logs are useful for debugging the application's deployment and runtime errors. |
| 26 | + |
| 27 | +--- |
| 28 | + |
| 29 | +## View Build Logs |
| 30 | + |
| 31 | +Build logs help you identify issues when a deployment fails with the status "Build failed". They can help you debug the build process and understand why the deployment didn't succeed. |
| 32 | + |
| 33 | +You can view the build logs for any deployment in your environment, including older deployments. |
| 34 | + |
| 35 | +To view the build logs for a deployment: |
| 36 | + |
| 37 | +1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization). |
| 38 | +2. Click on the project that the deployment belongs to. |
| 39 | +3. Click on the environment that the deployment belongs to, such as "Production". |
| 40 | +4. Under the "Deployments" section, find the deployment you want to view the build logs for and click on it. |
| 41 | + |
| 42 | +This will open the deployment details page, where you can see the build logs. The build logs are updated in real time as the build process runs, so you can see the progress and any errors that occur during the build. |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +### Search Build Logs |
| 47 | + |
| 48 | +You can search the build logs using the search bar at the top right of the "Build logs" section. This is useful for finding specific messages or errors in the logs. |
| 49 | + |
| 50 | +For example, you can search for keywords like "error" or "warning" to quickly locate issues in the build process. |
| 51 | + |
| 52 | +When you enter the search term, you'll see how many results match your search. You can then move between the results using the up and down arrows next to the search bar. The matching text will be highlighted in the logs. |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +### Expand and Collapse Build Logs |
| 57 | + |
| 58 | +Logs for steps in the build process can be expanded or collapsed to improve readability. This is useful when you have many log messages and want to focus on specific parts of the build process. |
| 59 | + |
| 60 | +By default, logs for all steps in the build process are expanded. You can collapse all logs by clicking the "Collapse all" button at the top right of the "Build logs" section. This will hide all the detailed logs and only show the titles of each step. |
| 61 | + |
| 62 | + |
| 63 | + |
| 64 | +You can also expand the logs of all steps in the build process by clicking the "Expand all" button at the top right. This will show all the detailed logs for each step. |
| 65 | + |
| 66 | + |
| 67 | + |
| 68 | +In addition, you can expand or collapse individual steps by clicking the arrow next to a step's title. This gives you more control over which parts of the logs you want to see or hide. |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | +### Pause Build Logs |
| 73 | + |
| 74 | +When you view the build logs while the build is still in progress, you can pause the logs to stop them from updating in real time. This is useful if you find a log message that you want to read more closely without it being pushed out of view by new log messages. |
| 75 | + |
| 76 | +To pause the build logs, click the "Pause" button at the bottom right of the page. This button is only shown when there are incoming log messages. When you pause the logs, the button will change to "Resume", allowing you to resume the live log updates. |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +### Download Build Logs |
| 81 | + |
| 82 | +You can download the build logs as a `.log` file for offline analysis, sharing with your team, or sharing with Cloud support if you need help debugging a build issue. |
| 83 | + |
| 84 | +To download build logs, click the <InlineIcon Icon={ArrowDownTray} alt="download" /> button at the top right of the "Build logs" section. This will download the logs in a `.log` file format, which you can open with any text editor. |
| 85 | + |
| 86 | + |
| 87 | + |
| 88 | +--- |
| 89 | + |
| 90 | +## View Runtime Logs |
| 91 | + |
| 92 | +Runtime logs are useful for debugging the live deployment of an environment, especially when the deployment's status is "Deploy failed". They include logs for: |
| 93 | + |
| 94 | +- Errors that occur during application startup. |
| 95 | +- Errors that occur when handling incoming HTTP requests, such as 404 errors or 500 server errors. |
| 96 | +- Scheduled jobs, subscribers, and background workflow executions not working as expected (if they log informational or error messages). |
| 97 | +- Other runtime issues that may occur while the application is running. |
| 98 | + |
| 99 | +You can only view the runtime logs of an environment's live deployment, as older deployments are no longer running and do not produce runtime logs. |
| 100 | + |
| 101 | +To view the runtime logs for an environment's live deployment: |
| 102 | + |
| 103 | +1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization). |
| 104 | +2. Click on the project that the environment belongs to. |
| 105 | +3. Click on the environment, such as "Production". |
| 106 | +4. Click the "Logs" tab at the top of the environment's dashboard. |
| 107 | + |
| 108 | +This will open the runtime logs page, where you can see the logs for the live deployment of the environment. |
| 109 | + |
| 110 | + |
| 111 | + |
| 112 | +### Search Runtime Logs |
| 113 | + |
| 114 | +You can search the runtime logs using the search bar at the top of the Logs page. This is useful for finding specific messages or errors in the logs. |
| 115 | + |
| 116 | +For example, you can search for keywords like "error" or an informational message that you log in your customizations to quickly locate issues in the runtime logs. |
| 117 | + |
| 118 | +When you enter the search term, you'll only see the logs that match your search. |
| 119 | + |
| 120 | + |
| 121 | + |
| 122 | +### Filter Runtime Logs |
| 123 | + |
| 124 | +The Filters sidebar of the Logs page allows you to filter the runtime logs based on various criteria. |
| 125 | + |
| 126 | +You can filter the runtime logs by: |
| 127 | + |
| 128 | +- **Timeline**: Select a specific time range to view logs from that period. For example, you can view the logs from the last hour. You can also select a custom time range. |
| 129 | +- **Level**: Filter logs by their severity level, such as "Info", "Warning", "Error", "Debug", or "HTTP". This helps you focus on specific types of logs that are relevant to your debugging needs. |
| 130 | +- **Status Code**: Filter logs by HTTP status codes, such as "200" or "500". This is useful to find problematic API routes and resolve their errors. |
| 131 | +- **Path**: Filter logs by an HTTP request path, such as `/admin/products`. This is useful to find logs related to specific API routes. |
| 132 | + |
| 133 | +Apply filters from the "Filters" sidebar. You can select multiple filters at once to narrow down the logs further. |
| 134 | + |
| 135 | + |
| 136 | + |
| 137 | +### Refresh Runtime Logs |
| 138 | + |
| 139 | +You can refresh the runtime logs to fetch the latest logs from the live deployment or to update the view after applying filters or search terms. |
| 140 | + |
| 141 | +To refresh the logs, click the <InlineIcon Icon={ArrowPath} alt="refresh" /> button at the top right of the Logs page. This will fetch the latest logs from the live deployment and update the view. |
| 142 | + |
| 143 | + |
| 144 | + |
| 145 | +### View Log Details |
| 146 | + |
| 147 | +When you click on a runtime log message, you can view its details and metadata in a sidebar on the right side of the Logs page. This includes information like the request size, timestamp, user agent, and more. |
| 148 | + |
| 149 | +From the log details sidebar, you can also: |
| 150 | + |
| 151 | +- Copy the log message to your clipboard by clicking the "Copy message" button at the top right of the sidebar. |
| 152 | +- View the JSON log details by clicking the <InlineIcon Icon={Brackets} alt="brackets" /> icon at the top right of the sidebar. This will open a JSON viewer where you can see the log details in a structured format. |
| 153 | + |
| 154 | + |
| 155 | + |
| 156 | +- Copy the log details in JSON format by clicking the "Copy as JSON" button at the bottom of the sidebar. |
| 157 | + |
| 158 | + |
| 159 | + |
| 160 | +You can copy the log message or JSON details to share them with your team or the Cloud support. |
| 161 | + |
| 162 | +### Filter by Log Metadata |
| 163 | + |
| 164 | +When you [view a log's details](#view-log-details), you can click on any of its metadata values to filter the logs by that value. This gives you a quick way to find all logs that share the same metadata, such as the same user agent or client IP. |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | +When you click on a metadata value, it will be added to the Filters sidebar, and the logs will be updated by that filter. |
| 169 | + |
| 170 | + |
| 171 | + |
| 172 | +### Download Runtime Logs |
| 173 | + |
| 174 | +You can download the runtime logs as a `.log` file for offline analysis, sharing with your team, or sharing with Cloud support if you need help debugging an issue. |
| 175 | + |
| 176 | +To download runtime logs, click the <InlineIcon Icon={ArrowDownTray} alt="download" /> button at the top right of the Logs page. This will download the logs currently shown in a `.json` file format, which you can open with any text editor. |
| 177 | + |
| 178 | +<Note title="Tip"> |
| 179 | + |
| 180 | +If you applied filters or search terms, only the logs shown that match those criteria will be downloaded. This allows you to download a specific subset of logs that are relevant to your debugging needs. |
| 181 | + |
| 182 | +</Note> |
| 183 | + |
| 184 | + |
0 commit comments