본문으로 건너뛰기

설정

​Configuration은 Crawlee의 설정 매개변수를 관리하는 클래스입니다. 기본적으로는 별도의 설정이 필요하지 않지만, 저장소 디렉터리 변경이나 상세 오류 로깅 활성화 등 특정 사용 사례에 따라 설정을 변경할 수 있습니다.

설정 매개변수를 변경하는 방법에는 세 가지가 있습니다:

  • 프로젝트에 crawlee.json 파일 추가
  • 환경 변수 설정
  • Configuration 클래스 사용

위의 방법들을 조합해서 사용할 수도 있지만, 다음과 같은 우선순위가 적용된다는 점을 유의해야 합니다: crawlee.json < 생성자 옵션 < 환경 변수

crawlee.json은 기본 설정입니다. Configuration 생성자에 제공된 옵션은 JSON에 지정된 옵션을 덮어씁니다. 환경 변수는 두 가지 모두를 덮어씁니다.

crawlee.json​

Crawlee를 구성하는 첫 번째 방법은 crawlee.json 파일을 사용하는 것입니다. ConfigurationOptions를 파일에 지정하고 프로젝트 루트에 위치시키기만 하면, Crawlee가 제공된 옵션을 전역 설정으로 사용합니다.

crawlee.json
{
  "persistStateIntervalMillis": 10000,
  "logLevel": "DEBUG"
}

crawlee.json을 사용하면 코드에서 추가 작업이 필요하지 않습니다:

import { CheerioCrawler, sleep } from 'crawlee';
// Configuration을 임포트하거나 크롤러에 전달하지 않아도 됩니다.
// 환경 변수도 설정하지 않습니다.
const crawler = new CheerioCrawler();

crawler.router.addDefaultHandler(async ({ request }) => {
    // 첫 번째 요청에서는 5초 대기하고
    // 두 번째 요청을 큐에 추가합니다
    if (request.url === 'https://www.example.com/1') {
        await sleep(5_000);
        await crawler.addRequests(['https://www.example.com/2'])
    }
    // 두 번째 요청에서는 10초 대기하고
    // 실행을 중단합니다
    if (request.url === 'https://www.example.com/2') {
        await sleep(10_000);
        process.exit(0);
    }
});

await crawler.run(['https://www.example.com/1']);

이 예제를 실행하면(프로젝트 루트에 persistStateIntervalMillis와 logLevel이 지정된 crawlee.json 파일이 있다고 가정), 기본 Key-Value 저장소에서 SDK_CRAWLER_STATISTICS 파일을 찾을 수 있습니다. 이 파일은 완료된 요청이 1개이고 크롤러 실행 시간이 약 10초임을 보여줍니다. 이는 crawlee.json에 설정된 대로 10초 후에 상태가 저장되었음을 확인해줍니다. 또한 crawlee.json에서 logLevel이 DEBUG로 설정되었기 때문에 터미널에서 INFO 로그 외에도 DEBUG 로그를 볼 수 있습니다.

환경 변수​

Crawlee를 구성하는 또 다른 방법은 환경 변수를 설정하는 것입니다. 다음은 사용자가 사용할 수 있는 Crawlee의 환경 변수 목록입니다.

주요 환경 변수​

다음 환경 변수들은 Crawlee의 작동 방식에 큰 영향을 미치며, 이들을 설정하거나 해제하면 동작이 크게 달라질 수 있습니다.

CRAWLEE_STORAGE_DIR​

KeyValueStore, Dataset, RequestQueue가 데이터를 저장하는 로컬 디렉터리의 경로를 정의합니다. 기본값은 ./storage입니다.

CRAWLEE_DEFAULT_DATASET_ID​

기본 데이터셋의 ID는 default입니다. 이 환경 변수를 설정하면 기본 데이터셋 ID가 제공된 값으로 변경됩니다.

CRAWLEE_DEFAULT_KEY_VALUE_STORE_ID​

기본 키-값 저장소의 ID는 default입니다. 이 환경 변수를 설정하면 기본 키-값 저장소 ID가 제공된 값으로 변경됩니다.

CRAWLEE_DEFAULT_REQUEST_QUEUE_ID​

기본 요청 큐의 ID는 default입니다. 이 환경 변수를 설정하면 기본 요청 큐 ID가 제공된 값으로 변경됩니다.

CRAWLEE_PURGE_ON_START​

저장소 디렉터리는 기본적으로 정리됩니다. false로 설정하면 크롤러 실행 시작 시 또는 저장소를 명시적으로 열 때(예: Dataset.open()을 통해) 로컬 저장소 디렉터리가 자동으로 정리되지 않습니다. 예를 들어 각 실행마다 데이터셋에 더 많은 항목을 추가하고 이전에 저장/수집된 항목을 유지하려는 경우에 유용합니다.

편의성 환경 변수​

다음 그룹에는 코드를 변경하지 않고도 특정 목표를 달성하는 데 도움이 되는 환경 변수가 포함됩니다. 예를 들어 일시적으로 로그 레벨을 DEBUG로 전환하거나 오류에 대한 상세 로깅을 활성화하는 등의 작업이 가능합니다.

CRAWLEE_HEADLESS​

1로 설정하면 Crawlee가 실행하는 웹 브라우저가 헤드리스 모드로 실행됩니다. 코드에서 이 설정을 재정의할 수 있습니다(예: launchPuppeteer() 함수에 headless: true 옵션을 전달). 기본적으로 브라우저는 헤드풀 모드(창이 있는 모드)로 실행됩니다.

CRAWLEE_LOG_LEVEL​

최소 로그 레벨을 지정합니다. 다음 값 중 하나를 사용할 수 있습니다(심각도 순): DEBUG, INFO, WARNING, ERROR, OFF. 기본적으로 로그 레벨은 INFO로 설정되어 있어 DEBUG 메시지는 콘솔에 출력되지 않습니다. 로깅 유틸리티에 대해서는 utils.log 네임스페이스를 참조하세요.

CRAWLEE_VERBOSE_LOG​

true로 설정하면 상세 로깅이 활성화됩니다. true로 명시적으로 설정되지 않은 경우, 요청 핸들러 내부에서 발생한 오류에 대해 요청이 재시도될 것으로 알고 있는 한 오류 메시지만 포함된 경고가 기록됩니다. 이는 일부 알려진 오류(예: 시간 초과 오류)에도 적용됩니다. 기본적으로 비활성화되어 있습니다.

CRAWLEE_MEMORY_MBYTES​

AutoscaledPool이 사용할 시스템 메모리 양을 메가바이트 단위로 설정합니다. 동시에 실행되는 작업의 수를 제한하는 데 사용됩니다. 기본적으로 사용할 수 있는 최대 메모리 양은 전체 시스템 메모리의 4분의 1로 설정됩니다. 예를 들어 8192MB의 메모리가 있는 시스템에서 자동 확장 기능은 최대 2048MB의 메모리만 사용합니다.

Configuration 클래스​

Crawlee 설정을 조정하는 마지막 방법은 코드에서 Configuration 클래스를 사용하는 것입니다.

전역 설정​

기본적으로 Configuration 클래스의 전역 싱글톤 인스턴스가 있으며, 이는 크롤러와 구성 가능한 동작에 의존하는 일부 다른 클래스에서 사용됩니다. 대부분의 경우 옵션을 조정할 필요가 없지만, 필요한 경우 Configuration.getGlobalConfig() 함수를 통해 접근할 수 있습니다. 이제 ConfigurationOptions를 쉽게 get하고 set할 수 있습니다.

import { CheerioCrawler, Configuration, sleep } from 'crawlee';

// 전역 설정을 가져옵니다
const config = Configuration.getGlobalConfig();
// 전역 설정의 'persistStateIntervalMillis' 옵션을
// 10초로 설정합니다
config.set('persistStateIntervalMillis', 10_000);

// 크롤러가 전역 설정을 사용하므로
// 설정을 크롤러에 전달할 필요가 없습니다
const crawler = new CheerioCrawler();

crawler.router.addDefaultHandler(async ({ request }) => {
    // 첫 번째 요청에서는 5초 대기하고
    // 두 번째 요청을 큐에 추가합니다
    if (request.url === 'https://www.example.com/1') {
        await sleep(5_000);
        await crawler.addRequests(['https://www.example.com/2'])
    }
    // 두 번째 요청에서는 10초 대기하고
    // 실행을 중단합니다
    if (request.url === 'https://www.example.com/2') {
        await sleep(10_000);
        process.exit(0);
    }
});

await crawler.run(['https://www.example.com/1']);

이는 crawlee.json 사용을 보여주는 데 사용했던 것과 거의 동일한 예제이지만, 이번에는 전역 설정을 사용한다는 점만 다릅니다. 이 예제를 실행하면 이전과 마찬가지로 기본 Key-Value 저장소에서 SDK_CRAWLER_STATISTICS 파일을 찾을 수 있으며, 동일한 수의 완료된 요청(1개)과 동일한 크롤러 실행 시간(~10초)을 보여줍니다. 이는 제공된 매개변수가 작동했음을 확인해줍니다: 전역 설정에서 설정한 대로 10초 후에 상태가 저장되었습니다.

노트

Configuration과 관련된 두 줄의 코드를 주석 처리하고 동일한 예제를 실행하면 기본 Key-Value 저장소에 SDK_CRAWLER_STATISTICS 파일이 저장되지 않습니다: persistStateIntervalMillis를 변경하지 않았기 때문에 Crawlee는 기본값인 60초를 사용했고, 크롤러는 첫 번째 상태 저장 전인 실행 시간 ~15초 후에 강제로 중단되었기 때문입니다.

사용자 정의 설정​

또는 사용자 정의 설정을 만들 수 있습니다. 이 경우 해당 설정을 사용할 클래스(예: 크롤러)에 전달해야 합니다. 이전 예제를 수정해보겠습니다:

import { CheerioCrawler, Configuration, sleep } from 'crawlee';

// 새로운 설정을 만듭니다
const config = new Configuration({
    // 'persistStateIntervalMillis' 옵션을 10초로 설정합니다
    persistStateIntervalMillis: 10_000,
});

// 이제 설정을 크롤러에 전달해야 합니다
const crawler = new CheerioCrawler({}, config);

crawler.router.addDefaultHandler(async ({ request }) => {
    // 첫 번째 요청에서는 5초 대기하고
    // 두 번째 요청을 큐에 추가합니다
    if (request.url === 'https://www.example.com/1') {
        await sleep(5_000);
        await crawler.addRequests(['https://www.example.com/2'])
    }
    // 두 번째 요청에서는 10초 대기하고
    // 실행을 중단합니다
    if (request.url === 'https://www.example.com/2') {
        await sleep(10_000);
        process.exit(0);
    }
});

await crawler.run(['https://www.example.com/1']);

이 예제를 실행하면 이전과 정확히 동일하게 작동하며, 실행 후 기본 Key-Value 저장소에 동일한 SDK_CRAWLER_STATISTICS 파일이 생성되어 동일한 수의 완료된 요청과 동일한 크롤러 실행 시간을 보여줍니다.

노트

설정을 크롤러에 전달하지 않으면 이번에는 다른 이유로 기본 Key-Value 저장소에 SDK_CRAWLER_STATISTICS 파일이 저장되지 않습니다. 크롤러에 설정을 전달하지 않았기 때문에 크롤러는 기본 persistStateIntervalMillis를 사용하는 전역 설정을 사용합니다. 따라서 이번에도 첫 번째 상태 저장 전인 실행이 중단되었습니다.