> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs & Monitoring

> Monitor your deployments and debug issues

Neptune provides access to your application logs and deployment status through your AI assistant.

## Waiting for Deployment

After deploying, you need to wait for your app to start before it's accessible. Ask your AI assistant:

> [!NOTE]
>
> "Wait for my deployment to complete"

> [!WARNING]
>
> **Don't skip this step!** Your app won't be accessible until the deployment finishes starting up. Your AI assistant will monitor the status and give you your public IP address when ready (typically 1-2 minutes).

## Viewing Logs

Ask your AI assistant:

> [!NOTE]
>
> "Show me the logs for my app"

This retrieves recent logs from your running container, including:

* Application stdout/stderr
* Startup messages
* Error traces
* Request logs (if your app logs them)

## Checking Deployment Status

Ask your AI assistant:

> [!NOTE]
>
> "What's the status of my deployment?"

This returns:

* **Infrastructure provisioning status**: Ready or provisioning
* **Service running status**: Running, Pending, Stopped, or Error
* **Public IP**: Your application's public IP address
* **Resource details**: Status of each storage bucket (including bucket ID), secret, and database

> [accordion] Example status response
>
> **Infrastructure:** Ready\
> **Service Status:** Running\
> **Deployment Revision:** 3\
> **Public IP:** 52.xxx.xxx.xxx
>
> **Resources:**
>
> * StorageBucket "uploads" - Available (aws\_id: bucket-abc123)
> * Secret "STRIPE\_API\_KEY" - Available
> * Database "my-app-db" - Available

## Debugging Failed Deployments

If your deployment isn't working, ask:

> [!NOTE]
>
> "My app isn't starting. Can you help debug?"

Your AI assistant will:

1. **Check status** - Identify if the service is in Error, Stopped, or stuck in Pending
2. **Get logs** - Retrieve recent logs to find error messages
3. **Analyze** - Identify the likely cause
4. **Suggest fixes** - Provide actionable solutions

### Common Issues

> [accordion] Service in 'Stopped' or 'Error' state
>
> Your application crashed. Check the logs for:
>
> * Unhandled exceptions
> * Missing configuration or secrets
> * Failed connections to external services
>
> **Fix:** Review the error, update your code, and redeploy.

> [accordion] Service stuck in 'Pending'
>
> The container is starting but not becoming healthy. Common causes:
>
> * App not listening on the expected port (default: 8080)
> * App taking too long to start
> * Health check failing
>
> **Fix:** Ensure your app listens on port 8080, or configure `port_mappings` in neptune.json.

> [accordion] Container exits immediately
>
> The process exits right after starting. Check for:
>
> * Missing dependencies
> * Configuration errors
> * Startup script issues
>
> **Fix:** Run your Docker container locally to debug:
>
> ```bash theme={"dark"}
> docker build -t myapp .
> docker run -p 8080:8080 myapp
> ```

> [accordion] Missing configuration or secrets
>
> Your app expects configuration that isn't available.
>
> **Fix:** Add secrets to your neptune.json and update your code to fetch them from AWS Secrets Manager:
>
> ```json theme={"dark"}
> {
>   "kind": "Secret",
>   "name": "DATABASE_URL"
> }
> ```
>
> If you want a managed Postgres database on Neptune, add a `Database` resource instead:
>
> ```json theme={"dark"}
> {
>   "kind": "Database",
>   "name": "my-app-db"
> }
> ```
>
> Then ask your AI assistant to provision and update your code.

## Best Practices

> [accordion] Add structured logging
>
> Use structured logging (JSON) for easier debugging:
>
> ```typescript theme={"dark"}
> console.log(JSON.stringify({
>   level: 'info',
>   message: 'Request processed',
>   path: req.path,
>   duration: Date.now() - start
> }));
> ```

> [accordion] Log startup information
>
> Log important information when your app starts:
>
> ```typescript theme={"dark"}
> console.log('Starting server...');
> console.log(`Port: ${process.env.PORT || 8080}`);
> console.log(`Environment: ${process.env.NODE_ENV}`);
> console.log('Server ready');
> ```

> [accordion] Handle errors gracefully
>
> Log errors with stack traces:
>
> ```typescript theme={"dark"}
> process.on('uncaughtException', (err) => {
>   console.error('Uncaught exception:', err.stack);
>   process.exit(1);
> });
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.