# Gửi dữ liệu

Source: https://instatus.com/help/vi/observability/send-logs

Instatus nhận log, trace và chỉ số qua OpenTelemetry (OTLP qua HTTPS). Có hai cách để kết nối ứng dụng. Hãy chọn một.

| At a glance | Details |
| :-- | :-- |
| [Nhanh nhất](https://instatus.com/help/vi/observability/send-logs#cách-1-sao-chép-prompt) | Sao chép prompt cho agent lập trình |
| [Thủ công](https://instatus.com/help/vi/observability/send-logs#cách-2-thiết-lập-thủ-công) | Chọn ngôn ngữ và dán mã |
| [Endpoint](https://instatus.com/help/vi/observability/send-logs#mỗi-yêu-cầu-cần-gì) | https://otel.instatus.com, thêm hai header |
| [Kiểm tra](https://instatus.com/help/vi/observability/send-logs#gửi-log-thử) | Một yêu cầu curl |
| [Không thấy gì?](https://instatus.com/help/vi/observability/send-logs#khắc-phục-sự-cố) | Khắc phục các sự cố thường gặp |

## Cách 1: Sao chép prompt

Cách nhanh nhất nếu bạn dùng agent lập trình như Claude Code, Cursor hoặc Copilot.

1. Mở **Observability** trên trang trạng thái của bạn.
2. Trong **Bao gồm**, đánh dấu những gì muốn gửi: **Log**, **Trace**, **Chỉ số**. Đánh dấu thêm **Bảng điều khiển khởi đầu** nếu sau này bạn muốn có bảng điều khiển sẵn cho các dịch vụ.
3. Nhấp **Sao chép prompt**.
4. Dán vào agent lập trình, trong dự án ứng dụng của bạn.
5. Đặt [khóa API](#tìm-khóa-api) vào biến môi trường `INSTATUS_API_KEY`, rồi chạy bài kiểm tra mà agent đề xuất.

![Thẻ thiết lập với log, trace và chỉ số để chọn cùng nút sao chép prompt](https://instatus.com/help/observability/setup.png)

Prompt yêu cầu agent dùng SDK OpenTelemetry chính thức cho ngôn ngữ của bạn, giữ thư viện ghi log hiện có, đọc khóa từ biến môi trường và không bao giờ commit nó. ID trang của bạn đã có sẵn trong đó.

## Cách 2: Thiết lập thủ công

1. Mở **Observability** trên trang trạng thái của bạn.
2. Nhấp **Thiết lập thủ công**.
3. Chọn ngôn ngữ: Node.js, Python, Go, Java, .NET, Ruby, PHP hoặc OpenTelemetry Collector.
4. Sao chép lệnh trong **Cài đặt** và chạy nó, sau đó sao chép mã trong **Cấu hình** vào ứng dụng.
5. Đặt biến môi trường `INSTATUS_API_KEY` bằng [khóa API](#tìm-khóa-api) của bạn và khởi động ứng dụng.

![Thiết lập thủ công với Node.js được chọn, hiển thị lệnh cài đặt và mã cấu hình](https://instatus.com/help/observability/setup-by-hand.png)

Mã trong bảng điều khiển đã điền sẵn ID trang của bạn. Các ví dụ tương tự có ở bên dưới nếu bạn muốn sao chép từ đây.

## Mỗi yêu cầu cần gì

| Mục          | Giá trị                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Endpoint      | `https://otel.instatus.com`. Log gửi đến `/v1/logs`, trace đến `/v1/traces`, chỉ số đến `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, với khóa của chủ sở hữu, quản trị viên hoặc biên tập viên của trang.                    |
| `X-Instatus-Site-Id` | ID của trang trạng thái chứa dữ liệu.                                                |
| Giao thức      | OTLP qua HTTP, dạng protobuf hoặc JSON. Nếu SDK mặc định dùng gRPC, hãy chuyển sang HTTP.          |

> Khóa API cho phép truy cập toàn bộ tài khoản của bạn. Hãy giữ nó trên máy chủ, trong biến môi trường. Tuyệt đối không đặt nó trong trình duyệt, ứng dụng di động hay kho mã công khai.

### Tìm khóa API

Mở menu ảnh đại diện, chọn **Cài đặt người dùng**, rồi **Nhà phát triển**, hoặc vào thẳng [cài đặt nhà phát triển](https://dashboard.instatus.com/developer). Nhấp **Sao chép** cạnh khóa.

![Khóa API trong cài đặt nhà phát triển, kèm nút sao chép](https://instatus.com/help/observability/api-key.png)

### Tìm ID trang

Hiếm khi cần: prompt và mã trong bảng điều khiển đã chứa sẵn. Để tự sao chép, nhấp chuột phải vào tên dự án ở đầu bảng điều khiển và chọn **Copy Project ID**.

![Copy Project ID trong menu của tên dự án](https://instatus.com/help/observability/copy-page-id.png)

## Gửi log thử

Một yêu cầu từ terminal là đủ để kiểm tra khóa và ID trang:

```bash
curl -X POST https://otel.instatus.com/v1/logs \
  -H "Authorization: Bearer $INSTATUS_API_KEY" \
  -H "X-Instatus-Site-Id: $INSTATUS_PAGE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "api" } }
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s)'000000000",
          "severityText": "INFO",
          "body": { "stringValue": "Hello from Instatus" }
        }]
      }]
    }]
  }'
```

Phản hồi `200` nghĩa là log đã được chấp nhận. Mở **Observability** → **Log**, log sẽ xuất hiện sau vài giây.

## Mọi ngôn ngữ, không cần sửa mã

Mọi SDK OpenTelemetry đều đọc cùng các biến môi trường. Với chúng, tính năng tự động đo đạc gửi trace, chỉ số và log mà không cần sửa mã:

```bash
export OTEL_SERVICE_NAME="api"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.instatus.com"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${INSTATUS_API_KEY},X-Instatus-Site-Id=${INSTATUS_PAGE_ID}"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
```

Dấu cách sau `Bearer` được viết là `%20`, vì biến header được mã hóa kiểu URL. Sau đó khởi động ứng dụng với tính năng tự động đo đạc cho ngôn ngữ của nó:

```bash
# Node.js
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register app.js

# Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py
```

Java, .NET, Go, Ruby và PHP có tính năng tự động đo đạc riêng và đọc cùng các biến. Xem [hướng dẫn zero-code của OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

Để gửi log từ mã, hãy cài SDK log:

```bash
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \
  @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
```

Thiết lập một lần khi ứng dụng khởi động:

```js
import { SeverityNumber } from '@opentelemetry/api-logs'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs'

const provider = new LoggerProvider({
  resource: resourceFromAttributes({ 'service.name': 'api' }),
  processors: [
    new BatchLogRecordProcessor(
      new OTLPLogExporter({
        url: 'https://otel.instatus.com/v1/logs',
        headers: {
          Authorization: `Bearer ${process.env.INSTATUS_API_KEY}`,
          'X-Instatus-Site-Id': process.env.INSTATUS_PAGE_ID
        }
      })
    )
  ]
})

const logger = provider.getLogger('api')

logger.emit({
  severityNumber: SeverityNumber.ERROR,
  severityText: 'ERROR',
  body: 'Payment failed: card declined',
  attributes: { 'customer.id': 'cus_123', route: '/v2/charges' }
})

process.on('beforeExit', () => provider.shutdown())
```

Đã ghi log bằng **pino** hoặc **winston**? Cứ giữ nguyên. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) và [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) gửi nguyên trạng mọi dòng log hiện có.

## Python

```bash
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

SDK gắn vào module `logging` của Python, nên các lệnh gọi `logging` hiện có được gửi nguyên trạng:

```python
import logging
import os

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.resources import Resource

provider = LoggerProvider(resource=Resource.create({"service.name": "worker"}))
provider.add_log_record_processor(
    BatchLogRecordProcessor(
        OTLPLogExporter(
            endpoint="https://otel.instatus.com/v1/logs",
            headers={
                "Authorization": f"Bearer {os.environ['INSTATUS_API_KEY']}",
                "X-Instatus-Site-Id": os.environ["INSTATUS_PAGE_ID"],
            },
        )
    )
)
set_logger_provider(provider)

logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=provider))
logging.getLogger().setLevel(logging.INFO)

logging.warning("Card declined for customer %s", "cus_123")
```

## OpenTelemetry Collector

Đã chạy OpenTelemetry Collector? Thêm Instatus làm exporter và giữ nguyên các ứng dụng:

```yaml
exporters:
  otlphttp/instatus:
    endpoint: https://otel.instatus.com
    headers:
      Authorization: Bearer ${env:INSTATUS_API_KEY}
      X-Instatus-Site-Id: ${env:INSTATUS_PAGE_ID}

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
```

Exporter tự thêm `/v1/logs`, `/v1/traces` và `/v1/metrics`, nên endpoint chỉ cần host. Để gửi tệp log, hãy thêm receiver `filelog` vào pipeline log.

## Gửi những gì

Instatus đọc các trường này. Mọi thứ khác được giữ làm thuộc tính để bạn tìm kiếm và lọc.

| Trường                       | Dùng cho                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (resource)      | Cột và bộ lọc **Dịch vụ**. Đặt nó trong mọi ứng dụng, worker và job. |
| `body`                             | Nội dung log, nơi tìm kiếm văn bản tự do hoạt động.                                                     |
| `severityText` hoặc `severityNumber` | Mức độ: `fatal`, `error`, `warn`, `info`, `debug` hoặc `trace`.                                  |
| `traceId` và `spanId`             | Liên kết log với trace của nó để bạn chuyển qua lại.                                          |
| Thuộc tính                     | Bất cứ thứ gì bạn thêm, như `customer.id` hoặc `http.route`. Mỗi thuộc tính trở thành một bộ lọc.               |

Các thuộc tính bắt đầu bằng `instatus.` được dành riêng và sẽ bị thay thế khi dữ liệu đến.

## Khắc phục sự cố

| Bạn thấy               | Cách xử lý                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Kiểm tra khóa và header `X-Instatus-Site-Id`. Chủ của khóa phải là chủ sở hữu, quản trị viên hoặc biên tập viên của trang.       |
| `400`                       | Phần thân không phải OTLP hợp lệ. Kiểm tra `Content-Type` và cấu trúc JSON trong [log thử](#gửi-log-thử).             |
| `429`                       | Hạn mức dữ liệu tháng này đã hết. Xem [gói và giới hạn](https://instatus.com/help/vi/observability#gói-và-giới-hạn).                    |
| `200`, nhưng không thấy gì | Đợi vài giây rồi kiểm tra khoảng thời gian. Log có dấu thời gian trong quá khứ chỉ hiện khi khoảng thời gian bao gồm nó. |
| Hoàn toàn không có gì              | SDK gửi theo lô. Hãy đảm bảo ứng dụng flush hoặc tắt provider trước khi thoát.                           |

Tạo lại khóa API trong cài đặt nhà phát triển sẽ vô hiệu hóa khóa cũ ngay lập tức, vì vậy hãy cập nhật mọi ứng dụng đang dùng nó trước.

- [Log](https://instatus.com/help/vi/observability/logs): Tìm kiếm, lọc và theo dõi log trực tiếp
- [Trace](https://instatus.com/help/vi/observability/traces): Xem mỗi yêu cầu tốn thời gian ở đâu
