🎯API Stability
Long-TermThis API is stable and will remain supported across versions with minimal breaking changes.

Summary

The createParserV2() mutation creates a parser in a LogScale repository. Parsers define how LogScale processes and extracts structured fields from incoming log events. Provide the parser script, tag field configuration, and optional test cases as a single CreateParserInputV2 input object.

To create a parser from a YAML specification, use createParserFromTemplate() instead. To copy an existing parser as a starting point, use cloneParser().

Syntax

graphql
createParserV2(
      input: CreateParserInputV2!
   ): Parser!

The mutation takes a single required argument, input, of type CreateParserInputV2!. The input object specifies the target repository, the parser script, tag field configuration, fields to exclude from usage calculations, and optional test cases. The mutation returns a Parser! object representing the created parser.

Example

Raw
graphql
mutation {
  createParserV2(input:
      { repositoryName: "humio",
        name: "myKvParser",
        script: "kvParse()",
        testCases: [{
          event: {rawString: "key=value"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: "key", expectedValue: "value"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}
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 {
  createParserV2(input:
      { repositoryName: \"humio\",
        name: \"myKvParser\",
        script: \"kvParse()\",
        testCases: [{
          event: {rawString: \"key=value\"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}"
}
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 {
  createParserV2(input:
      { repositoryName: \"humio\",
        name: \"myKvParser\",
        script: \"kvParse()\",
        testCases: [{
          event: {rawString: \"key=value\"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}"
}
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 { ^
  createParserV2(input: ^
      { repositoryName: \"humio\", ^
        name: \"myKvParser\", ^
        script: \"kvParse()\", ^
        testCases: [{ ^
          event: {rawString: \"key=value\"},  ^
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}], ^
        }], ^
        fieldsToTag: [], ^
        fieldsToBeRemovedBeforeParsing: [] ^
      }) ^
  { id } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  createParserV2(input:
      { repositoryName: \"humio\",
        name: \"myKvParser\",
        script: \"kvParse()\",
        testCases: [{
          event: {rawString: \"key=value\"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}"
}'
    "$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 {
  createParserV2(input:
      { repositoryName: \"humio\",
        name: \"myKvParser\",
        script: \"kvParse()\",
        testCases: [{
          event: {rawString: \"key=value\"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}";
$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 {
  createParserV2(input:
      { repositoryName: \"humio\",
        name: \"myKvParser\",
        script: \"kvParse()\",
        testCases: [{
          event: {rawString: \"key=value\"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}"
}'''

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 {
  createParserV2(input:
      { repositoryName: \"humio\",
        name: \"myKvParser\",
        script: \"kvParse()\",
        testCases: [{
          event: {rawString: \"key=value\"}, 
          outputAssertions: [{outputEventIndex: 0, assertions: {fieldsHaveValues: [{fieldName: \"key\", expectedValue: \"value\"}]}}],
        }],
        fieldsToTag: [],
        fieldsToBeRemovedBeforeParsing: []
      })
  { id }
}"
}
);


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();

Input Parameters

The input argument accepts a CreateParserInputV2 object. Provide repositoryName and name to identify the target repository and name the parser. The fields fieldsToBeRemovedBeforeParsing, fieldsToTag, and testCases are required; pass an empty array for any list field you do not need. The following table describes all available fields.

Table: CreateParserInputV2 Input Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
allowOverwritingExistingParserBoolean  Long-Term Allows saving a parser with a name that is already in use, by overwriting the parser that previously had the name.
fieldsToBeRemovedBeforeParsingStringyes Long-Term A list of fields that will be removed from the event before it's parsed. These fields will not be included when calculating usage.
fieldsToTagStringyes Long-Term Fields that are used as tags.
languageVersionLanguageVersionInputType  Long-Term A specific language version. See LanguageVersionInputType.
nameStringyes Long-Term The name to use for the parser.
repositoryNameRepoOrViewNameyes Long-Term The repository where the parser is located. RepoOrViewName is a scalar.
scriptStringyes Long-Term The parser script that is executed for every incoming event.
testCasesParserTestCaseInputyes Long-Term Test cases that can be used to help verify that the parser works as expected. See ParserTestCaseInput.

The testCases field accepts an array of ParserTestCaseInput objects. Each test case pairs a raw input event with output field assertions. The following table describes the fields in that subtype:

Table: ParserTestCaseInput Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
eventParserTestEventInputyes Long-Term The event to parse and on which to test. See ParserTestEventInput.
outputAssertionsParserTestCaseAssertionsForOutputInputyes Long-Term Assertions on the shape of the test case output events. The list consists of key-value pairs to be treated as a map-construct, where the index of the output event is the key, and the assertions are the value. See ParserTestCaseAssertionsForOutputInput.

Returned Values

The mutation returns a Parser! object describing the created parser. Request id to obtain the unique identifier for the new parser. Use this identifier with subsequent mutations and queries, such as testParserV2() and updateParserV2(). The returned object also includes the parser name, script, tag configuration, and test cases. The following table lists all available fields:

Table: Parser Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
createdInfoAssetCommitMetadata  Long-Term Metadata related to the creation of the parser. See AssetCommitMetadata.
descriptionString  Long-Term A description of the parser.
displayNameStringyes Long-Term The full name of the parser, including package information if part of an application.
fieldsToBeRemovedBeforeParsingStringyes Long-Term A list of fields that will be removed from the event before it's parsed. These fields will not be included when calculating usage.
fieldsToTagStringyes Long-Term The fields that are used as tags.
idStringyes Long-Term The unique identifier of the parser.
isBuiltInBooleanyes Long-Term True if the parser is one of LogScale's built-in parsers.
isOverriddenBooleanyes Short-Term True if the parser is one of LogScale's built-in parsers, and it is overridden by a custom parser.
languageVersionLanguageVersionyes Long-Term The language version used by the parser. See LanguageVersion.
modifiedInfoAssetCommitMetadata  Long-Term Metadata related to the latest modification of the parser. See AssetCommitMetadata.
nameStringyes Long-Term The name of the parser.
originDisplayStringStringyes Short-Term The origin of a parser. Can either be "Built in", "Local" or a package.
overridesBuiltInParserBooleanyes Short-Term True if the parser is overrides one of LogScale's built-in parsers.
packagePackageInstallation  Long-Term The package associated with the parser, if any. See PackageInstallation.
packageIdVersionedPackageSpecifier  Long-Term The identifier of the package used, if one. VersionedPackageSpecifier is a scalar.
scriptStringyes Long-Term The parser script that is executed for every incoming event.
testCasesParserTestCaseyes Long-Term Test cases that can be used to help verify that the parser works as expected. See ParserTestCase.
yamlTemplateYAMLyes Long-Term A template that can be used to recreate the parser. YAML is a scalar.