Data streams

출처: 문서

본문

데이터 스트림

데이터 스트림은 문서를 쓰고 검색하는 단일 이름으로, OpenSearch가 대신 롤오버해 주는 일련의 숨겨진 인덱스가 그 뒤를 받쳐줘요. 인덱싱 요청은 현재 쓰기 인덱스로 향하고, 검색 요청은 모든 백킹 인덱스로 향해요.

데이터 스트림은 로그, 이벤트, 메트릭처럼 지속적으로 생성되는 시계열 데이터, 즉 문서가 빠르게 쌓이고 오래된 문서는 절대 업데이트되지 않는 데이터를 위한 기능이에요. 이런 데이터를 일반 인덱스로 관리하려면 롤오버 별칭을 만들고, 쓰기 인덱스를 지정하고, 새 인덱스마다 동일한 매핑과 설정을 반복해서 지정해야 해요. 데이터 스트림은 이 모든 작업을 인덱스 템플릿 하나로 처리해요.

데이터 스트림에는 다음과 같은 특징이 있어요:

• 모든 문서에는 타임스탬프 필드가 반드시 포함되어야 해요. 타임스탬프 필드가 없는 문서는 거절돼요.
• 데이터 스트림은 append-only예요. 데이터 스트림 이름으로 보낸 인덱싱 요청은 새 문서를 생성하는 것만 가능해요. 기존 문서를 업데이트하거나 삭제하려면 update by query 또는 delete by query 요청을 사용하거나, 해당 문서가 들어 있는 백킹 인덱스로 요청을 보내세요. 자세한 내용은 데이터 스트림에서 문서 업데이트 및 삭제를 참고하세요.
• 백킹 인덱스는 .ds-<data-stream>-<generation> 형식의 이름을 가지며 숨겨져 있어요. generation 번호는 롤오버할 때마다 증가해요.
• 데이터 스트림은 data_stream 객체가 포함된 인덱스 템플릿으로만 생성할 수 있어요.

백킹 인덱스의 나이, 크기, 문서 개수를 기준으로 롤오버와 삭제를 자동화하려면 Index State Management (ISM) 정책을 연결하세요. 정책은 각 백킹 인덱스가 생성될 때 적용되기 때문에, 데이터 스트림에 정책을 연결하면 이후에 만들어질 백킹 인덱스에만 영향을 줘요. 정책이 백킹 인덱스에서 해당 정보를 가져오기 때문에 rollover_alias 설정은 제공할 필요가 없어요.

데이터 스트림에 세분화된 권한을 정의하려면 인덱스 이름을 사용하듯 데이터 스트림 이름을 사용하세요. 자세한 내용은 Permissions를 참고하세요.

데이터 스트림용 인덱스 템플릿 만들기

데이터 스트림은 data_stream 객체가 포함된 인덱스 템플릿으로 정의돼요. 템플릿의 인덱스 패턴은 만들려는 데이터 스트림의 이름과 일치해야 해요:

PUT _index_template/logs-template
{
  "index_patterns": [
    "logs-*"
  ],
  "data_stream": {},
  "priority": 100
}

{% include copy-curl.html %}

데이터 스트림 템플릿은 자신의 인덱스 패턴을 독점적으로 차지해요. 이 템플릿이 존재하는 동안 logs-로 시작하는 이름의 일반 인덱스를 생성하려고 하면 cannot create index with name [...], because it matches with template [logs-template] that creates data streams only 오류와 함께 실패해요. 일반 인덱스와 겹치지 않도록 충분히 좁은 패턴을 선택하세요. {: .note}

이 템플릿으로 생성한 데이터 스트림에 인덱싱되는 문서에는 @timestamp 필드가 반드시 포함되어야 해요. 다른 필드 이름을 사용하려면 timestamp_field에 지정하세요. template 객체는 일반 인덱스 템플릿과 동일한 설정, 매핑, 별칭을 받아들여 각 백킹 인덱스에 적용해요:

PUT _index_template/logs-nginx-template
{
  "index_patterns": [
    "logs-nginx"
  ],
  "data_stream": {
    "timestamp_field": {
      "name": "request_time"
    }
  },
  "priority": 200,
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    }
  }
}

{% include copy-curl.html %}

logs-nginx라는 이름은 두 템플릿 모두와 일치해요. OpenSearch는 우선순위가 더 높은 logs-nginx-template을 적용해요. 자세한 내용은 Index templates를 참고하세요.

데이터 스트림 만들기

첫 번째 백킹 인덱스를 초기화하려면 데이터 스트림을 명시적으로 생성하세요:

PUT _data_stream/logs-redis

{% include copy-curl.html %}

이 단계를 건너뛰고 바로 인덱싱을 시작할 수도 있어요. 일치하는 템플릿에 data_stream 객체가 포함되어 있기 때문에, OpenSearch는 첫 인덱싱 요청에서 데이터 스트림을 생성해요:

POST logs-staging/_doc
{
  "message": "login attempt failed",
  "@timestamp": "2013-03-01T00:00:00"
}

{% include copy-curl.html %}

데이터 스트림에 데이터 색인하기

일반 인덱스에 사용하는 것과 동일한 Document APIs를 사용해 데이터 스트림 이름으로 문서를 인덱싱하세요. 각 문서에는 템플릿에 정의된 타임스탬프 필드가 반드시 포함되어야 해요:

POST logs-redis/_doc?refresh=true
{
  "message": "login attempt",
  "@timestamp": "2013-03-01T00:00:00"
}

{% include copy-curl.html %}

refresh=true 파라미터는 문서를 즉시 검색할 수 있게 만들어서, 다음 섹션의 검색에서 해당 문서가 반환되도록 해요. 프로덕션 환경에서는 refresh interval이 이를 처리하므로 이 파라미터는 생략하세요.

데이터 스트림은 operation type이 create인 쓰기 요청만 받아들여요. 자동 생성된 문서 ID를 사용하는 POST <data-stream>/_doc 요청은 create operation이에요. 문서 ID를 지정하려면 _create 엔드포인트를 사용하거나 op_type=create 쿼리 파라미터를 설정하세요. op_type=create 없이 보낸 PUT <data-stream>/_doc/<id> 요청은 index operation이 되어 거절돼요. 다음 요청은 ID가 1인 문서를 생성해요:

PUT logs-redis/_create/1?refresh=true
{
  "message": "logout",
  "@timestamp": "2013-03-01T00:05:00"
}

{% include copy-curl.html %}

Bulk API 요청에서는 각 문서에 대해 create 액션을 사용하세요. index 액션은 데이터 스트림에서 거절돼요:

POST _bulk?refresh=true
{ "create": { "_index": "logs-redis", "_id": "2" } }
{ "message": "session expired", "@timestamp": "2013-03-01T00:10:00" }
{ "create": { "_index": "logs-redis", "_id": "3" } }
{ "message": "password reset", "@timestamp": "2013-03-01T00:15:00" }

{% include copy-curl.html %}

응답의 각 항목은 문서를 저장하는 백킹 인덱스를 보여줘요. 예를 들어 "_index": ".ds-logs-redis-000001"처럼요.

데이터 스트림 검색하기

인덱스나 별칭을 검색하듯 데이터 스트림을 검색하세요. 요청은 모든 백킹 인덱스를 대상으로 해요:

GET logs-redis/_search
{
  "query": {
    "match": {
      "message": "login"
    }
  }
}

{% include copy-curl.html %}

각 검색 결과의 _index 필드에는 해당 문서를 담고 있는 백킹 인덱스의 이름이 들어 있어요:

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.13076457,
    "hits": [
      {
        "_index": ".ds-logs-redis-000001",
        "_id": "iCnxtaABPpBDXMo4kFWl",
        "_score": 0.13076457,
        "_source": {
          "message": "login attempt",
          "@timestamp": "2013-03-01T00:00:00"
        }
      }
    ]
  }
}

asynchronous search, SQL, PPL를 사용해 데이터 스트림을 쿼리할 수도 있고, 인덱스나 별칭에서 하듯 시각화를 만들 수도 있어요.

데이터 스트림에서 문서 업데이트 및 삭제하기

데이터 스트림 이름으로 보낸 단일 문서 업데이트 및 삭제 요청은 거절돼요. 데이터 스트림의 문서를 변경하려면 다음 방법 중 하나를 사용하세요.

쿼리로 문서 업데이트 또는 삭제하기

Update by Query와 Delete by Query API는 데이터 스트림 이름을 받아들여서, 모든 백킹 인덱스에 걸쳐 일치하는 문서를 처리해요. 다음 요청은 expired가 포함된 문서의 message를 변경해요:

POST logs-redis/_update_by_query?refresh=true
{
  "query": {
    "match": {
      "message": "expired"
    }
  },
  "script": {
    "source": "ctx._source.message = \"session timed out\""
  }
}

{% include copy-curl.html %}

다음 요청은 password가 포함된 문서를 삭제해요:

POST logs-redis/_delete_by_query?refresh=true
{
  "query": {
    "match": {
      "message": "password"
    }
  }
}

{% include copy-curl.html %}

단일 문서 업데이트 또는 삭제하기

단일 문서를 업데이트하거나 삭제하려면 해당 문서가 들어 있는 백킹 인덱스로 요청을 보내세요. 백킹 인덱스를 찾으려면 데이터 스트림에서 해당 문서를 검색하세요. 다음 요청은 ID가 1인 문서와 함께 sequence number와 primary term을 반환해요:

GET logs-redis/_search?seq_no_primary_term=true
{
  "query": {
    "ids": {
      "values": ["1"]
    }
  }
}

{% include copy-curl.html %}

검색 결과의 _index 필드에는 백킹 인덱스의 이름이 들어 있어요:

{
  ...
  "hits": {
    "hits": [
      {
        "_index": ".ds-logs-redis-000001",
        "_id": "1",
        "_seq_no": 1,
        "_primary_term": 1,
        "_score": 1.0,
        "_source": {
          "message": "logout",
          "@timestamp": "2013-03-01T00:05:00"
        }
      }
    ]
  }
}

업데이트 요청은 백킹 인덱스로 보내세요. 검색 이후에 이루어진 변경 사항을 덮어쓰지 않도록, 검색 응답에서 얻은 if_seq_no와 if_primary_term 값을 포함하세요:

POST .ds-logs-redis-000001/_update/1?if_seq_no=1&if_primary_term=1&refresh=true
{
  "doc": {
    "message": "logout requested"
  }
}

{% include copy-curl.html %}

마찬가지로 문서를 삭제하려면 백킹 인덱스로 요청을 보내세요:

DELETE .ds-logs-redis-000001/_doc/1?refresh=true

{% include copy-curl.html %}

데이터 스트림 롤오버하기

롤오버는 새 백킹 인덱스를 생성하고, 이를 데이터 스트림의 쓰기 인덱스로 만들어요. 수동으로 롤오버하려면 다음 요청을 사용하세요:

POST logs-redis/_rollover

{% include copy-curl.html %}

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-logs-redis-000001",
  "new_index": ".ds-logs-redis-000002",
  "rolled_over": true,
  "dry_run": false,
  "conditions": {}
}

데이터 스트림의 generation 번호는 롤오버할 때마다 증가해요. 롤오버 조건과 파라미터는 Roll Over API를 참고하세요. 자동으로 롤오버하려면 ISM policy를 사용하세요.

데이터 스트림 살펴보기

다음 표는 자주 사용하는 데이터 스트림 요청을 정리한 거예요. get 요청의 응답에는 타임스탬프 필드 이름, 백킹 인덱스, generation 번호, 데이터 스트림을 생성한 템플릿, 그리고 백킹 인덱스 중 가장 낮은 상태를 나타내는 status가 포함돼요.

예를 들어 다음 요청은 한 번 롤오버한 후의 logs-redis 데이터 스트림을 반환해요:

GET _data_stream/logs-redis

{% include copy-curl.html %}

{
  "data_streams": [
    {
      "name": "logs-redis",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-logs-redis-000001",
          "index_uuid": "Xq04oCQ-TiCjIL81Q_ZL9g"
        },
        {
          "index_name": ".ds-logs-redis-000002",
          "index_uuid": "UBX0UhE9TFKTi-jB5mB7tQ"
        }
      ],
      "generation": 2,
      "status": "YELLOW",
      "template": "logs-template"
    }
  ]
}

와일드카드를 사용하면 여러 데이터 스트림을 한 번에 지정할 수 있어요. 데이터 스트림을 삭제하면 백킹 인덱스도 함께 삭제되며 되돌릴 수 없어요. 주기적으로 데이터를 제거하려면 대신 ISM 정책을 사용하세요. {: .warning}

모든 데이터 스트림 operation과 파라미터는 Data stream APIs를 참고하세요.

데이터 스트림의 백킹 인덱스 수정하기

Modify Data Stream API를 사용하면 기존 데이터 스트림의 백킹 인덱스를 추가하거나 제거할 수 있어요. 이 작업은 메타데이터만 다루는 operation이기 때문에, 기존 일반 인덱스를 데이터 스트림으로 옮기거나 데이터를 삭제하지 않고 백킹 인덱스를 분리할 수 있어요. 스냅샷 복원 중에 복원된 백킹 인덱스를 데이터 스트림에 연결하려면 Restore Snapshot API에서 attach_to_data_stream을 true로 설정하세요.

OpenSearch Dashboards의 데이터 스트림

Index Management 페이지로 이동하려면 상단 메뉴에서 Management > Index Management로 가세요. Data streams를 선택하면 클러스터에 있는 데이터 스트림 목록이 표시돼요.

Data streams 테이블에는 다음 컬럼이 있어요.

다음 이미지는 Data streams 페이지를 보여줘요.

데이터 스트림 보기

Data stream name 컬럼에서 데이터 스트림을 선택하세요. Data stream details에 이름, 상태, 템플릿, 백킹 인덱스 개수, 타임스탬프 필드 이름이 표시돼요. Backing indexes에는 각 백킹 인덱스의 health, status, 크기, 문서 개수, 샤드 개수, write index 여부, ISM 정책 관리 여부가 리스트로 표시돼요. 백킹 인덱스를 선택하면 일반 인덱스와 동일한 형식으로 세부 정보를 볼 수 있어요. 자세한 내용은 인덱스 세부 정보 보기를 참고하세요.

인덱스 목록에서 백킹 인덱스 보기

백킹 인덱스는 기본적으로 Indexes 테이블에서 숨겨져 있어요:

1. Index Management에서 Indexes를 선택하세요.
2. Show data stream indexes를 선택하세요. 그러면 테이블에 Data stream 컬럼이 추가되어 각 백킹 인덱스가 어느 데이터 스트림에 속하는지 보여주고, 테이블 헤더에는 Data streams 목록이 추가돼요.
3. 원하는 경우 Data streams 목록에서 데이터 스트림을 하나 이상 선택해 해당 데이터 스트림의 백킹 인덱스만 표시할 수 있어요.

데이터 스트림 생성

데이터 스트림은 타입이 Data streams인 인덱스 템플릿을 통해서만 생성할 수 있어요. 생성 방법은 인덱스 템플릿 생성을 참고하세요.

1. Index Management에서 Data streams를 선택한 다음 Create data stream을 선택하세요.

2. Data stream name에 이름 입력을 시작하세요. 입력하는 동안 일치하는 인덱스 패턴과 해당 인덱스 템플릿 목록이 나타나요.

3. 목록에서 인덱스 패턴을 선택한 다음, 패턴과 일치하도록 이름을 완성하세요.

   Matching template에는 이 패턴을 포함하는 인덱스 템플릿이 표시돼요. Inherited settings from template의 값은 읽기 전용이에요.

4. Create data stream을 선택하세요.

데이터 스트림 삭제

1. Index Management에서 Data streams를 선택하세요.
2. 삭제하려는 각 데이터 스트림 옆의 체크박스를 선택하세요.
3. Actions를 선택한 다음 Delete를 선택하세요.
4. 확인 대화상자에 delete를 입력한 다음 Delete를 선택하세요.

데이터 스트림을 삭제하면 해당 백킹 인덱스도 함께 삭제돼요. 데이터는 복구할 수 없어요. {: .warning}

데이터 스트림 롤오버

1. Index Management에서 Data streams를 선택하세요.
2. Actions를 선택한 다음 Roll over를 선택하세요.
3. Configure source에서 롤오버할 데이터 스트림을 선택하세요.
4. Roll over를 선택하세요.

데이터 스트림 세부 정보 페이지의 Backing indexes 테이블에 새 write index가 포함돼요.

Refresh, flush, clear cache, force merge 작업도 Data streams 페이지에서 사용할 수 있으며, 선택한 데이터 스트림의 백킹 인덱스에 적용돼요. 이 절차에 대한 내용은 OpenSearch Dashboards의 인덱스 유지 관리를 참고하세요.

관련 문서

• 데이터 스트림 API
• 인덱스 템플릿
• Index State Management
• 인덱스 유지 관리

더 알아보기 (Learn more)

• 원문 전체: https://docs.opensearch.org/latest/im-plugin/data-streams/