s3ConfigureArchiving()

🎯API Stability

Short-TermThis API may change in future versions. Use with caution in production environments.

Summary

The s3ConfigureArchiving() mutation configures S3 archiving for a repository, setting the target bucket, AWS region, and storage format. Run s3ArchivingRequiresRole() before this mutation to determine whether an IAM role ARN is required for your configuration. After configuring, use s3EnableArchiving() to start the archiving job.

After configuring archiving, use s3EnableArchiving() to start the archiving job, or s3DisableArchiving() to stop it. To reset the archiving state and mark all segment files as unarchived, use s3ResetArchiving().

Hide Query Example

Show S3 Archiving Query

To retrieve the current S3 archiving configuration for a repository, use the repository() query:

graphql

query {
     repository ( name: "humio" )
      { s3ArchivingConfiguration { bucket, disabled, startFrom } }
   }

For more information on S3 storage, see the S3 Archiving documentation page.

Syntax

graphql

s3ConfigureArchiving(
      repositoryName: String!,
      bucket: String!,
      region: String!,
      format: S3ArchivingFormat!,
      tagOrderInName: [String!],
      startFromDateTime: DateTime,
      roleArn: String,
      endAtDateTime: DateTime
   ): BooleanResultType!

The required parameters are repositoryName, bucket, region, and format. Use startFromDateTime and endAtDateTime to set the time range for archiving. Provide roleArn when the bucket requires IAM role-based access. The Input Parameters table describes all available options.

The mutation returns a BooleanResultType! confirming whether the configuration was applied successfully. See the Returned Values section.

Example

Raw

graphql

mutation {
  s3ConfigureArchiving(
    repositoryName: "humio",
    bucket: "pale-1",
    region: "us-west-1",
    format: RAW,
    tagOrderInName: ["admin", "other"]
  )
  { result }
}

Mac OS or Linux (curl)

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  s3ConfigureArchiving(
    repositoryName: \"humio\",
    bucket: \"pale-1\",
    region: \"us-west-1\",
    format: RAW,
    tagOrderInName: [\"admin\", \"other\"]
  )
  { result }
}"
}
EOF

Mac OS or Linux (curl) One-line

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  s3ConfigureArchiving(
    repositoryName: \"humio\",
    bucket: \"pale-1\",
    region: \"us-west-1\",
    format: RAW,
    tagOrderInName: [\"admin\", \"other\"]
  )
  { result }
}"
}
EOF

Windows Cmd and curl

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  s3ConfigureArchiving( ^
    repositoryName: \"humio\", ^
    bucket: \"pale-1\", ^
    region: \"us-west-1\", ^
    format: RAW, ^
    tagOrderInName: [\"admin\", \"other\"] ^
  ) ^
  { result } ^
}" ^
} '

Windows Powershell and curl

powershell

curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  s3ConfigureArchiving(
    repositoryName: \"humio\",
    bucket: \"pale-1\",
    region: \"us-west-1\",
    format: RAW,
    tagOrderInName: [\"admin\", \"other\"]
  )
  { result }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"

Perl

perl

#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  s3ConfigureArchiving(
    repositoryName: \"humio\",
    bucket: \"pale-1\",
    region: \"us-west-1\",
    format: RAW,
    tagOrderInName: [\"admin\", \"other\"]
  )
  { result }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";

Python

python

#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  s3ConfigureArchiving(
    repositoryName: \"humio\",
    bucket: \"pale-1\",
    region: \"us-west-1\",
    format: RAW,
    tagOrderInName: [\"admin\", \"other\"]
  )
  { result }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)

Node.js

javascript

const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  s3ConfigureArchiving(
    repositoryName: \"humio\",
    bucket: \"pale-1\",
    region: \"us-west-1\",
    format: RAW,
    tagOrderInName: [\"admin\", \"other\"]
  )
  { result }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();

Example Responses

Success (HTTP Response Code 200 OK)

json

{
  "data": {
    "s3ConfigureArchiving": {
      "result": true
    }
  }
}

Input Parameters

Specify the target repository, AWS region, S3 bucket, and storage format. To limit the archiving time range, provide startFromDateTime and endAtDateTime. Supply roleArn when the bucket requires IAM role-based access.

Table: Input Parameters and Datatypes

Parameter	Type	Required	Description
This table contains all input parameters for this mutation. One parameter uses a special datatype; the following table documents its allowed values.
bucket	string	yes	The name of the S3 bucket where LogScale writes archived segments.
endAtDateTime	datetime		The DateTime after which LogScale stops archiving new segments. Omit to archive without an end bound.
format	S3ArchivingFormat	yes	The format used to store archived segments in S3. See the following table for allowed values.
region	string	yes	The AWS region where the S3 bucket resides, for example `us-east-1`.
repositoryName	string	yes	The name of the repository to configure for S3 archiving.
roleArn	string		The ARN of the AWS IAM role LogScale assumes to access the S3 bucket. Required when the bucket enforces role-based access.
startFromDateTime	datetime		The DateTime from which LogScale begins archiving segments. Omit to archive from the earliest available data.
tagOrderInName	[string]		An ordered list of tag names that LogScale uses to construct the S3 object key path. The order determines the directory hierarchy in the bucket.

The format parameter accepts one of the S3ArchivingFormat enum values. The following table documents the available options.

Returned Values

The mutation returns a BooleanResultType! indicating whether the S3 archiving configuration was applied successfully. A true result confirms the settings were saved.

Table: BooleanResultType Datatype

Parameter	Type	Required	Default	Stability	Availability	Description
result	Boolean	yes		`Long-Term`		Whether the mutation was performed successfully.

Versions of this Page

GraphQL Mutations

GraphQL API

GraphQL Queries

GraphQL Datatypes