Extensions 2.0 - Is there detailed documentation on the activationSchema.json file and ALL of its possible fields and values?

[36Krazyfists]

I can find info on the extension.yaml file, but very little about activationSchema.json...  Given how important this file seems to be, I would think this has to be documented somewhere, right?

The most I found was on the dt-extensions-python-sdk page and it confuses me greatly.  It seems to insinuate that the Create command of the python-sdk will generate the Activation Schema file automatically.  However, I'm looking at the rabbitMQ Python extension's ActivationSchema.json file and I see things defined in it that I have a hard time believing were filled out automatically based on data it has collected from the script.  Not to mention that there is a python method for getting the contents of the activationSchema.json file, so how can the activationSchema.json file be automatically generated based on script contents if the script needs to get data from the file itself?

We need documentation that details the following:
- Are the activationSchema.json file contents completely automated, or are we supposed to be configuring it?

- What do the fields in this file do and what are all of the possible values for each field?

- And, most importantly, why would we use a field?  This is something that is missing from a lot of Dynatrace's documentation (not all, some sections are pretty good).  Meaning that, even when they explain what something is, I still have no clue what it does or why I would use it (for example, fastCheck...  The only place I've seen it explained is in the context of the SNMP extension, but I see it used in Python extensions and I don't know how or why to use it...).

[Mike_L · Accepted solution]

There is currently no documentation for this. I'll forward your thread to the product manager.

[Joseph_Hobbs]

Yes please!

[36Krazyfists]

Hi.  Is there at least a schema file somewhere for the activationSchema.json file?  I want to know what the possible fields and values are that can be used there (yes, I can look at other extensions' activationSchema files, but that still doesn't give me a complete picture, nor does it give me a real explanation of what and why something is used).

I've looked in the /v2/extensions/schema api endpoint and there doesn't appear to be a schema file that explains the activationSchema.json file.

I've also found this link at the top of the activationSchema.json files of a few extensions developed by Dynatrace (like the newer forgerock identity cloud extension for example), but this link doesn't appear to be publicly accessible:
https://artifactory.lab.dynatrace.org/artifactory/configuration-core-release/com/dynatrace/configura...

I'm looking back at some of the documentation for the old EF1.0 and it is pretty fantastic.  Is there any plan to get that level of detail for the 2.0 framework?  It's been a while and still nothing.  But honestly, I'll just take a schema file for that activationSchema.json file at this point...  Just... something...

[36Krazyfists]

Hi Mike.  Any word on this yet?  It's been almost a year (and extensions 2.0 has been around for several more years prior to that) and we still don't have proper documentation (that I can find) on the activationSchema.json file...

Sure, looking at other extensions can help, but ultimately we need to know what should/can be in there and how to use it to write good python extensions.  Currently, we're all just kind of winging it.

Using the vsCode extension can help because it will show some auto-complete, but that still isn't the same as seeing the whole schema at once to get an understanding of how it all works and ties together.

While documentation would be nice, I'd settle for just the schema file at this point...

[Mike_L]

Let me raise it again with product management.

[36Krazyfists]

Thank you Mike!

[36Krazyfists]

Hey @Mike_L, any word?

I'm really struggling here and could use some documentation to exlpain what these fields do and what's possible with the ActivationSchema.json file.

Finding various examples with other existing extensions and examining their json file is tedious and doesn't really show what is possible.

And, to be fair, this issue is not limited to just that file.  A similar issue with the extensions.yaml file.  For example, I recently discovered the wmi extension can run WMI WQL queries and return the results as Logs instead of just metrics.  This isn't documented anywhere.  I just happened to find it on a community post and it is used in the MS Exchange extension.  But without that post, I would have probably never found it.

My point is, how many other useful features and capabilities are there that we don't know about because of the absence of documentation listing all of the possible fields, parameters, and descriptions of the ActivationSchema.json and extensions.yaml files?

[Mike_L]

There is currently a rework going on for the extension documentation. I'll raise to the team that they need to consider the activation schema as part of that rework as it's very complicated to write Python extensions without documentation.

[36Krazyfists]

Thanks Mike.

Yeah, I hope it's sooner rather than later.  Extensions 2.0 have been out for many years now.  It's a shame the docs are so lacking.

[36Krazyfists]

Oh, quick idea @Mike_L:

Maybe make the activationSchema.json schema definition file publicly available?  It's not as good as actual documentation, but it would at least be something we can use in the meantime until the documentation is ready.  As I said in a previous reply in this thread, I see this URL in many of the activationSchema.json files, but the URL is not publicly available:

https://artifactory.lab.dynatrace.org/artifactory/configuration-core-release/com/dynatrace/configura...

Anyways, I have a few example questions; and this is just a drop in the bucket; but these are the kinds of things we're hoping for in the documentation:

• When defining elements in the ActivationSchema.json file, there is a "type" property.  Most of the time, I just see things like "object", "list", and "text" defined in there, but what are all the other possible types?
• I sometimes see a "subtype" property defined for certain elements.  One example of a subtype I saw had a value of "url".  Again, what are all the possible subtypes and when/why would I use them?
• Sometimes I see a "constraints" property defined.  What are all the possible constraints and what does each constraint do?
  • One weird thing I see constraints used for sometimes is to define a "type" of "NOT_EMPTY", which I find odd because for every element you can define a property of "nullable" and set it to either true or false.  By setting "nullable" to true, wouldn't that be the same as setting the "NOT_EMPTY" constraint?  I don't get the difference.
• Looking at the ElasticSearch extension's activationSchema.json file, I see some elements (like the "zone"filters" element) have a "metadata" property.  Again, what are all the possible metadata properties and values we can set and when/why would we use them?

Those are just a very small sample of questions that I have.

On top of stuff like that, documenting the general layout of the file and how everything connects in that file would also help.  Ideally, you guys would provide example file snippets along with screenshots of how those snippets' settings affect the UI in the Monitoring Configuration.

  Explaining is great, but showing while you explain is even better!

Hope that helps and thanks again.

[Mike_L]

I've been asking for the schema to be made public, the challenge is that it's our full settings 2.0 schema, and there would be so much in there that the expectation from our product management is that it'd create more questions than it'd solve. We're hoping to add something into the vscode extension from my team to simplify it for everyone.

[Joseph_Hobbs]

Those of us willing to dig through it will really appreciate the info.  Those who aren't willing are going to ask for help either way...  As someone willing to dig in, I'd rather have too much info than none at all.

[36Krazyfists]

Yeah, I get it, but I gotta agree with Joseph_Hobbs.  I'd rather have too much info than not enough.

Anyways, hopefully the example questions I provided above give you guys an idea of what we're looking for and I am excited to see the improvements in vsCode as well.

Thanks yet again!

[36Krazyfists]

Hi Mike,

Any update on the extension doc progress, specifically around the Activation Schema?

[Mike_L]

There is no news. The rework is ongoing though so hopefully something will come. We spend quite some time trying things out in my team, so basing it off existing extensions is easiest still.

[Joseph_Hobbs]

In the meantime, check out this extension (downloadable from the public hub).  Lots of good examples!

https://www.dynatrace.com/hub/detail/remote-unix-monitoring-20/?query=linux+remote&filter=all#overvi...

[pahofmann]

It's been a while, are there any updates on documentation for this? 

[MathieuB]

We are about one week before the end of EF1 and we still not have a proper documentation for EF2...
The only solution is to contact support each time we have a question.

[pahofmann]

Yes, it's quite tedious I have to say.  

The v2 Framework has so many great new features but without documentation it just takes a lot of time. 

I'd recommend looking at the unix remote extension from the hub, can copy a lot of examples from there.

[MathieuB]

Hi everyone,
I don't know if anyone watch this topic anymore regarding that it has been marked "solved".

I contact the support team and the final answer is that :

1. There is no real developer documentation, but there are working on it (without giving any date..)
2. The only "documentation" they have is that :
   https://developer.dynatrace.com/develop/dynatrace-extensions-vscode/guides/create_extension/#activat...

@pahofmann can you give me the link of the Unix remote extension you talk ? Thanks

So on our side, we cannot migrate to EF2.
We will try to stay on EF1 without any support : now when we contact Dynatrace support on EF1 issue, the only answer we get is "migrate to EF2 Extension".

[Joseph_Hobbs]

It's linked above...

https://www.dynatrace.com/hub/detail/remote-unix-monitoring-20/?query=linux+remote&filter=all#overvi...

[dylan_taelemans]

Hey, 
The best documentation I’ve found is on this page:
https://dynatrace-extensions.github.io/dt-extensions-python-sdk/index.html#documentation
https://dynatrace-extensions.github.io/dt-extensions-python-sdk/guides/extension_structure.html
I hope this helps.  😉

[36Krazyfists]

Yes, they've had those docs for a while now.  Unfortunately, they are not super helpful.  They don't have the data that is being asked for in this thread.  Thanks though.

[Julius_Loman]

The best approach so far is to have a look at activationSchema for some existing extension that is available in the HUB. 

[36Krazyfists]

Yeah, still leaves a lot to be desired.  Ideally, I'd like to see the schema for all of the available params and values.

Existing extensions are great but dissecting them and figuring out what and why they do the things they do is laborious and often incomplete.

For example:

How many different "type" and "subType" values are there?   What are all the "type" and "subType" values?  What do the various "subType" values do? 

How does the "preCondition" object work?  When can we use it and when can we not use it?  Is there a "postCondition" object?

In the "uiCustomization" object, what are all the available objects and properties we can use there?  Is it just "tabs", or are there other customizations?  

I could go on and on.  Any time I work on a custom python extension, I find a dozen or more objects that I wonder about and then I wonder how many more helpful objects and properties there are that I don't even know about... 

My point being, without the schema, it's very hard to know what is and isn't possible and how to effectively use that page.

I understand the activationSchema.json file's schema is part of a bigger schema doc and there is concern that sharing it could cause confusion, but I still feel like it should be released. The kind of people that would even bother wanting to look at it should be the kind of people that can pick through it and find what they need.

Or you guys can have an intern or junior associate pull out all of the activationSchema parts from the larger schema file and put it into its own document page and share that with us.   

Extensions 2.0 has been out for a very long time at this point, and we still don't have effective documentation.   It can be very frustrating to work with.